CI CD - JohanDevl/Export_Trakt_4_Letterboxd GitHub Wiki

CI/CD Pipeline Documentation

This project uses GitHub Actions for continuous integration and continuous deployment. The CI/CD pipeline automates testing, building, and deployment of the application.

Workflow Components

1. Go Tests Workflow

The tests workflow runs all unit and integration tests for the Go application.

File: .github/workflows/go-tests.yml

Triggered by:

  • Push to main and feature/* branches
  • Pull requests to main branch

Steps:

  1. Check out the code
  2. Set up Go environment
  3. Install dependencies
  4. Run all tests with coverage tracking
  5. Generate a coverage report
  6. Upload the coverage report as an artifact
  7. Verify the code coverage meets minimum threshold (70%)

Example output:

✓ Testing package pkg/config
✓ Testing package pkg/api
✓ Testing package pkg/export
✓ Testing package pkg/i18n
✓ Testing package pkg/logger
✓ Testing integration tests
Coverage: 82.5% of statements

2. Docker Build Workflow

This workflow builds and publishes Docker images for the application.

File: .github/workflows/docker-build.yml

Triggered by:

  • Push to main and feature/go-migration branches
  • Pull requests to main branch
  • Release events
  • Manual trigger via workflow_dispatch

Jobs:

  1. Build: Builds multi-platform Docker images

    • Platforms: linux/amd64, linux/arm64, linux/arm/v7
    • Sets up Docker buildx and QEMU
    • Logs in to Docker Hub and GitHub Container Registry
    • Builds and pushes images with appropriate tags
    • Scans images for vulnerabilities using Trivy

  2. Test: Tests the built Docker image

    • Pulls the image
    • Verifies the image runs correctly
    • Checks basic functionality

  3. Notify: Notifies about build status on release events

    • Creates a GitHub comment with build status
    • Provides image usage instructions

Docker Image Tags:

  • latest - Always points to the most recent release
  • vX.Y.Z - For version releases
  • sha-XXXXXXX - Git commit SHA
  • Branch name - For builds from specific branches

Docker Images

The Docker image is built using a multi-stage build process:

  1. Build stage: Uses Go to compile the application
  2. Final stage: Creates a minimal Alpine-based image

Image URLs:

  • Docker Hub: johandevl/export-trakt-4-letterboxd
  • GitHub Packages: ghcr.io/johandevl/export_trakt_4_letterboxd

Image Features:

  • Multi-architecture support
  • Minimal size (<20MB)
  • Non-root user execution
  • Health checks included

Volumes:

  • /app/config - Configuration files
  • /app/logs - Log files
  • /app/exports - Export output files

Environment Variables:

  • TZ: Timezone (default: UTC)
  • LOG_LEVEL: Logging level (default: info)
  • LANGUAGE: Interface language (default: en)

Usage:

docker run -v $(pwd)/config:/app/config \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/exports:/app/exports \
  johandevl/export-trakt-4-letterboxd:latest

Quality Standards

The CI pipeline enforces the following quality standards:

  1. Test Coverage: Minimum 70% code coverage required
  2. Passing Tests: All tests must pass
  3. Build Verification: Application must build successfully
  4. Security Scanning: Docker images are scanned for vulnerabilities

Release Process

The automated release process for the application:

  1. Create a GitHub release: Tag a new version (e.g., v1.0.0)
  2. Automated actions:
    • Tests are run
    • Docker images are built for multiple platforms
    • Images are tagged with version numbers
    • Release assets (binaries) are attached to the GitHub release
    • Release notes are generated from recent commits

Local Development

To run the same checks locally as the CI pipeline:

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html

# Build Docker image locally
docker build -t export-trakt-local -f Dockerfile .

Troubleshooting

Common CI/CD Issues

  1. Failed Tests:

    • Check the workflow logs to identify which tests failed
    • Run tests locally to debug the issue

  2. Docker Build Failures:

    • Verify the Dockerfile and dependencies
    • Check if multi-platform support is causing issues

  3. Missing Credentials:

    • Ensure repository secrets are correctly set for Docker Hub and GitHub Packages

GitHub Actions Workflow Status

You can check the status of all workflows in the Actions tab of the GitHub repository: https://github.com/JohanDevl/Export_Trakt_4_Letterboxd/actions