114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# 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
|