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](https://hub.docker.com/)
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

```yaml
# 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

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

### Release Workflow

```yaml
# 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:**
   ```bash
   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:**
   ```bash
   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:

```markdown
[![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:**
   ```yaml
   env:
     REGISTRY: your-registry.com
   ```

2. **Update image names:**
   ```yaml
   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:

```yaml
- 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:

```yaml
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