UptimeKuma-DiscordBot/GITEA_ACTIONS_SETUP.md

Gitea Actions Setup for Docker Build and Publish

This document explains how to set up Gitea Actions to automatically build and publish Docker images for the UptimeKuma Discord Bot project.

Overview

The Gitea Actions workflows provide:

• Automated Docker image building for both Discord bot and web backend
• Multi-platform support (linux/amd64, linux/arm64)
• Security scanning with Trivy
• Automated releases with changelog generation
• Docker Compose testing to ensure everything works together

Workflows

1. Docker Build (docker-build.yml)

Triggers:

• Push to main or develop branches
• Push of version tags (v*)
• Pull requests to main

Features:

• Builds both Discord bot and web backend images
• Multi-platform builds (AMD64, ARM64)
• Pushes to Docker Hub on non-PR events
• Generates Software Bill of Materials (SBOM)
• Security vulnerability scanning
• GitHub Actions cache for faster builds

2. Docker Compose Test (docker-compose-test.yml)

Triggers:

• Push to main or develop branches
• Pull requests to main

Features:

• Tests the complete Docker Compose setup
• Validates Dockerfile syntax with hadolint
• Checks service health and connectivity
• Validates environment variable configuration

3. Release (release.yml)

Triggers:

• Push of version tags (v*)

Features:

• Creates GitHub releases automatically
• Generates changelog from git commits
• Updates release notes with Docker image information

Required Secrets

Configure these secrets in your Gitea repository settings:

Docker Hub Secrets

• DOCKER_USERNAME: Your Docker Hub username
• DOCKER_PASSWORD: Your Docker Hub access token (not password)

How to Get Docker Hub Token

1. Go to Docker Hub
2. Sign in to your account
3. Go to Account Settings → Security
4. Create a new access token
5. Copy the token and use it as DOCKER_PASSWORD

Setup Instructions

1. Enable Gitea Actions

1. Go to your Gitea repository
2. Navigate to Settings → Actions
3. Enable Actions if not already enabled

2. Configure Secrets

1. Go to Settings → Secrets
2. Add the following secrets:

Secret Name	Description	Example
DOCKER_USERNAME	Docker Hub username	myusername
DOCKER_PASSWORD	Docker Hub access token	dckr_pat_...

3. Test the Workflow

1. Push a commit to the main branch
2. Go to Actions tab in your repository
3. Watch the workflow execution
4. Check the logs for any errors

Workflow Details

Docker Build Workflow

# Key features:
- Multi-platform builds (linux/amd64, linux/arm64)
- Automatic tagging based on git refs
- Build cache for faster subsequent builds
- Security scanning with Trivy
- SBOM generation for supply chain security

Image Tags Generated:

• latest (for main branch)
• main (branch name)
• v1.0.0 (version tags)
• 1.0 (major.minor)
• 1 (major)

Docker Compose Test Workflow

# Key features:
- Validates Docker Compose configuration
- Tests service startup and health checks
- Lints Dockerfiles with hadolint
- Validates environment variable usage

Release Workflow

# Key features:
- Automatic release creation on version tags
- Changelog generation from git commits
- Release notes with Docker image information
- Quick start instructions included

Usage Examples

Creating a Release

1. Create and push a version tag:

   git tag v1.0.0
   git push origin v1.0.0
   

2. The workflow will:

   • Build Docker images with version tags
   • Create a GitHub release
   • Generate changelog
   • Publish images to Docker Hub

Testing Changes

1. Create a pull request:

   git checkout -b feature/new-feature
   git commit -m "Add new feature"
   git push origin feature/new-feature
   

2. The workflow will:

   • Build images (but not push)
   • Run security scans
   • Test Docker Compose setup
   • Validate configuration

Monitoring and Troubleshooting

Viewing Workflow Runs

1. Go to Actions tab in your repository
2. Click on a workflow run to see details
3. Expand job steps to view logs

Common Issues

1. Docker Hub Authentication Failed

Error: Cannot perform an interactive login from a non TTY device

Solution: Check that DOCKER_USERNAME and DOCKER_PASSWORD secrets are correctly set.

2. Build Cache Issues

Error: failed to solve: failed to compute cache key

Solution: The workflow will automatically retry without cache on failure.

3. Security Scan Failures

Error: Trivy found vulnerabilities

Solution: Review the security scan results and update base images if needed.

Workflow Status Badge

Add this to your README.md to show workflow status:

[![Docker Build](https://gitea.example.com/api/badges/username/repo/status.svg)](https://gitea.example.com/username/repo/actions)

Advanced Configuration

Custom Registry

To use a different registry than Docker Hub:

1. Update environment variables in workflows:

   env:
     REGISTRY: your-registry.com
   

2. Update image names:

   env:
     IMAGE_NAME_DISCORD_BOT: your-org/uptime-kuma-discord-bot
     IMAGE_NAME_WEB_BACKEND: your-org/uptime-kuma-web-backend
   

Build Arguments

To pass build arguments to Docker builds:

- name: Build and push Discord Bot image
  uses: docker/build-push-action@v5
  with:
    context: ./Bot
    file: ./Bot/Dockerfile
    build-args: |
      NODE_VERSION=18
      BUILD_DATE=${{ github.event.head_commit.timestamp }}

Matrix Builds

To build for multiple Node.js versions:

strategy:
  matrix:
    node-version: [16, 18, 20]

Security Considerations

Secrets Management

• Never commit secrets to the repository
• Use Gitea's built-in secrets management
• Rotate Docker Hub tokens regularly
• Use least-privilege access tokens

Image Security

• Base images are automatically scanned for vulnerabilities
• SBOMs are generated for supply chain transparency
• Multi-platform builds ensure compatibility
• Non-root users in containers for security

Workflow Security

• Workflows run in isolated environments
• Secrets are encrypted and only available during execution
• No secrets are logged or exposed in outputs

Best Practices

1. Version Tagging

• Use semantic versioning (v1.0.0)
• Tag releases consistently
• Include meaningful commit messages

2. Branch Strategy

• Use main for production releases
• Use develop for integration testing
• Use feature branches for new development

3. Monitoring

• Monitor workflow execution regularly
• Set up notifications for failures
• Review security scan results

4. Maintenance

• Keep base images updated
• Review and update workflow dependencies
• Monitor for deprecated actions

Support

For issues with Gitea Actions:

1. Check the workflow logs first
2. Verify secrets are correctly configured
3. Ensure Gitea Actions is enabled
4. Check Gitea version compatibility
5. Review this documentation

Contributing

When contributing to the workflows:

1. Test changes in a fork first
2. Update documentation as needed
3. Follow the existing workflow patterns
4. Ensure backward compatibility
5. Add appropriate error handling