component-system/.gitea/workflows

Gitea CI/CD Pipeline

This directory contains Gitea Actions workflows for automated code quality checks and Docker image publishing.

Workflows

1. Code Quality (code-quality.yml)

Runs on every push to main and pull requests targeting main. This workflow:

• Sets up Elixir 1.15 with OTP 26
• Installs dependencies and restores caches for faster builds
• Checks for unused dependencies
• Compiles with warnings as errors (enforces clean compilation)
• Validates code formatting (mix format --check-formatted)
• Runs the full test suite
• Executes mix precommit to ensure all quality checks pass

Important: This workflow will fail if mix precommit hasn't been run locally, ensuring code quality standards are maintained.

2. Docker Build and Publish (docker-build.yml)

Publishes Docker images to the Gitea container registry:

• Snapshot builds: For every commit to main branch
  • Tagged as: latest, main, snapshot-{sha}
• Release builds: For every tagged commit (e.g., v1.0.0)
  • Tagged as: {tag-name}, latest

Features:

• Multi-platform builds (linux/amd64, linux/arm64)
• Build caching for faster subsequent builds
• Comprehensive metadata and labels

Setup Requirements

1. Gitea Configuration

Update the REGISTRY environment variable in docker-build.yml:

env:
  REGISTRY: your-gitea-instance.com  # Replace with your Gitea URL

2. Required Secrets

Create the following secret in your Gitea repository settings:

• GITEAX_TOKEN: Personal Access Token with package write permissions
  • Go to your Gitea instance → Settings → Applications → Generate New Token
  • Select "write:packages" scope
  • Add this token as a repository secret named GITEAX_TOKEN

Gitea Actions currently do not support package repository authorization like GitHub Actions, so a PAT is necessary for publishing. See https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692.

3. Container Registry

Enable the container registry in your Gitea instance if not already enabled. The published images will be available at:

{your-gitea-instance}/{owner}/components-elixir

Usage

For Developers

Before pushing code, always run:

mix precommit

This ensures your code will pass the CI quality checks.

For Releases

To create a release:

1. Tag your commit: git tag v1.0.0
2. Push the tag: git push origin v1.0.0
3. The pipeline will automatically build and publish a release image

For Snapshots

Snapshot builds are created automatically for every commit to the main branch.

Docker Image Usage

Pull and run the latest snapshot:

docker pull {your-gitea-instance}/{owner}/components-elixir:latest
docker run -p 4000:4000 {your-gitea-instance}/{owner}/components-elixir:latest

Pull and run a specific release:

docker pull {your-gitea-instance}/{owner}/components-elixir:v1.0.0
docker run -p 4000:4000 {your-gitea-instance}/{owner}/components-elixir:v1.0.0

Gitea Actions Limitations

This pipeline is designed with Gitea Actions limitations in mind:

• No concurrency, run-name, permissions, or timeout-minutes support
• Limited expression support (only always() function)
• Simple runs-on syntax only
• No package repository authorization - uses Personal Access Token instead

Troubleshooting

Authentication Issues

• Ensure GITEAX_TOKEN secret is properly set with package write permissions
• Verify the token hasn't expired

Build Failures

• Check that mix precommit passes locally
• Ensure all tests pass with the test database configuration
• Verify Docker build works locally: docker build -t test .

Registry Issues

• Confirm container registry is enabled in your Gitea instance
• Check that the registry URL in the workflow matches your Gitea instance