# Forgejo Actions Configuration

This directory contains Forgejo Actions workflows (GitHub Actions-compatible) for CI/CD.

## Migration from GitLab CI

The `.forgejo/workflows/build-deploy.yml` file replaces `.gitlab-ci.yml` with equivalent functionality:

### Key Differences

| GitLab CI | Forgejo Actions |
|-----------|-----------------|
| `stages:` | `jobs:` (jobs run in dependency order) |
| `tags: [home]` | `runs-on: ubuntu-latest` |
| `rules:` | `on:` (trigger conditions) |
| `$CI_COMMIT_SHA` | `${{ github.sha }}` |
| `$CI_REGISTRY_IMAGE` | `${{ secrets.REGISTRY_URL }}/${{ github.repository }}` |
| `workflow.auto_cancel` | `concurrency.cancel-in-progress` |
| Docker-in-Docker service | `docker/build-push-action@v5` |

### Required Secrets

Configure these in your Forgejo repository settings (Settings → Secrets):

1. **`REGISTRY_URL`** - Container registry URL (e.g., `registry.gitlab.com`)
2. **`REGISTRY_USER`** - Container registry username
3. **`REGISTRY_PASSWORD`** - Container registry password/token

### Required Runner Setup

The workflow uses `ubuntu-latest` as the target label, which should match most Linux-based runners.

**To check your runner's labels:**
1. Go to your Forgejo repository → Settings → Actions → Runners
2. Look for the "Labels" column for your registered runner
3. If you see `ubuntu-latest` or `ubuntu-22.04`, the workflow should work

**To register a runner with specific labels:**
```bash
# Register with custom labels
./act_runner register --labels ubuntu-latest,custom-label

# Or edit the runner config after registration
# Edit .runner file or config.yaml and add labels
```

The runner must have:

1. **Docker** - For building images
2. **kubectl** - Pre-configured with cluster access
   - Context: `towerops/towerops:home-cluster-agent` must exist
   - Namespace: `towerops` with deployment named `towerops`

### Workflow Stages

#### 1. Build
- Triggers on push to `main` branch
- Checks out code
- Logs into container registry
- Builds Docker image using `k8s/Dockerfile`
- Uses layer caching from `:latest` tag for faster builds
- Pushes two tags:
  - `<registry>/<repo>:<commit-sha>` - Specific version
  - `<registry>/<repo>:latest` - Latest build

#### 2. Deploy
- Depends on successful build
- Uses `kubectl` to update Kubernetes deployment
- Sets image to the newly built commit SHA
- Adds `DEPLOY_TIMESTAMP` environment variable
- Lets Kubernetes handle rollout asynchronously

### Testing the Workflow

To test without deploying:

```bash
# Validate workflow syntax
act --list -W .forgejo/workflows/build-deploy.yml

# Run build job locally (if act is installed)
act push -W .forgejo/workflows/build-deploy.yml -j build
```

### Comparison to GitLab CI

**Advantages:**
- Uses official Docker actions (more reliable layer caching)
- Better concurrency control (auto-cancels old runs)
- Clearer job dependencies with `needs:`

**Equivalent Features:**
- Same Docker build process with BUILDKIT and caching
- Same kubectl deployment commands
- Same environment protection (production)
- Same branch filtering (main only)

### Troubleshooting

**Build fails with registry authentication:**
- Verify `REGISTRY_USER` and `REGISTRY_PASSWORD` secrets are set
- Check runner has network access to registry

**Deploy fails with kubectl errors:**
- Verify runner has kubectl installed: `kubectl version --client`
- Check kubeconfig context exists: `kubectl config get-contexts`
- Verify cluster access: `kubectl get deployments -n towerops`

**Runner not picking up jobs:**
- Check runner labels: Repository → Settings → Actions → Runners
- Verify runner has `ubuntu-latest` label (or update workflow to match your runner's labels)
- Check runner logs: `journalctl -u act_runner -f` or check runner process output
- Ensure runner is online and connected (green status in UI)
- If runner has different labels, update `runs-on:` in workflow to match