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