basil/.gitea/GITEA_ACTIONS_SETUP.md

Gitea Actions Setup Guide

This guide explains how to set up and configure Gitea Actions for the Basil project.

Prerequisites

1. Gitea instance with Actions enabled (Gitea 1.19+)
2. Act runner installed and configured
3. PostgreSQL available for testing
4. Docker (optional, for Docker-related workflows)

Enabling Gitea Actions

1. Enable Actions in Gitea

Edit your Gitea configuration file (app.ini):

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://github.com  ; or your own Gitea instance

Restart Gitea:

systemctl restart gitea

2. Install Act Runner

The act runner executes Gitea Actions workflows.

Install via Docker:

docker pull gitea/act_runner:latest

Install via binary:

# Download from Gitea releases
wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64
chmod +x act_runner-linux-amd64
mv act_runner-linux-amd64 /usr/local/bin/act_runner

3. Register the Runner

1. Get registration token from Gitea:

   • Go to your repository settings
   • Navigate to Actions → Runners
   • Copy the registration token

2. Register the runner:

act_runner register \
  --instance https://your-gitea-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name basil-runner

3. Start the runner:

# Run in foreground
act_runner daemon

# Or run as systemd service
sudo systemctl enable act_runner
sudo systemctl start act_runner

Repository Configuration

Required Secrets

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

DOCKER_REGISTRY=registry.example.com
DOCKER_USERNAME=your-username
DOCKER_PASSWORD=your-password-or-token

Optional Secrets

For production deployments:

DEPLOY_SSH_KEY=your-ssh-private-key
DEPLOY_HOST=your-server.com
DEPLOY_USER=deploy
SENTRY_DSN=your-sentry-dsn

Workflow Files

The project includes 4 main workflows in .gitea/workflows/:

1. CI Pipeline (ci.yml)

Triggers:

• Push to main, master, develop
• Pull requests

Jobs:

• Linting
• Unit tests (API, Web, Shared)
• Build verification
• Coverage reports

Database: Uses PostgreSQL service container

2. E2E Tests (e2e.yml)

Triggers:

• Push to main, master
• Pull requests to main, master
• Nightly schedule (2 AM UTC)

Jobs:

• Full E2E test suite
• Mobile browser tests (on main branch only)

Services: PostgreSQL

3. Security Scanning (security.yml)

Triggers:

• Push to main, master, develop
• Pull requests to main, master
• Weekly schedule (Monday 9 AM UTC)

Jobs:

• NPM dependency audit
• License checking
• Code quality scanning
• Docker image security

4. Docker Build & Deploy (docker.yml)

Triggers:

• Push to main, master
• Version tags (v*)

Jobs:

• Build Docker images
• Push to registry
• Deploy to staging (develop branch)
• Deploy to production (version tags)

Testing the Setup

1. Verify Runner Connection

Check runner status in repository settings:

• Settings → Actions → Runners
• Ensure runner shows as "online"

2. Trigger a Test Workflow

Create a test file .gitea/workflows/test.yml:

name: Test Workflow

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Echo test
        run: echo "Gitea Actions is working!"

Push to trigger:

git add .gitea/workflows/test.yml
git commit -m "test: add test workflow"
git push

Check Actions tab in your repository to see the workflow run.

3. Test Main CI Workflow

# Make a small change
echo "# Test" >> README.md

# Commit and push
git add README.md
git commit -m "test: trigger CI workflow"
git push

# Check Actions tab to see CI pipeline run

Monitoring Workflows

View Workflow Runs

1. Go to repository → Actions tab
2. Click on workflow run to see details
3. Expand jobs to see individual steps
4. View logs for debugging

Workflow Status Badges

Add to your README.md:

![CI](https://your-gitea.com/username/basil/actions/workflows/ci.yml/badge.svg)
![E2E](https://your-gitea.com/username/basil/actions/workflows/e2e.yml/badge.svg)
![Security](https://your-gitea.com/username/basil/actions/workflows/security.yml/badge.svg)

Troubleshooting

Runner Not Connecting

1. Check runner logs:

   journalctl -u act_runner -f
   

2. Verify token: Ensure registration token is correct

3. Check network: Runner must reach Gitea instance

Workflow Failing

1. Check logs in Actions tab
2. Verify secrets are configured
3. Test locally with act:

   # Install act (GitHub Actions locally)
   curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
   
   # Run workflow locally
   act -W .gitea/workflows/ci.yml
   

Database Connection Issues

1. Verify PostgreSQL service in workflow:

   services:
     postgres:
       image: postgres:16
       # ... health checks ...
   

2. Check DATABASE_URL environment variable

3. Ensure migrations run before tests

Docker Build Failures

1. Verify Docker is available on runner
2. Check Dockerfile paths are correct
3. Ensure registry credentials are valid
4. Test build locally:

   docker-compose build
   

Performance Optimization

Caching Dependencies

Workflows use npm cache:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

Parallel Jobs

Jobs run in parallel by default. Use needs: to create dependencies:

jobs:
  test:
    runs-on: ubuntu-latest
    # ...

  deploy:
    needs: test  # Wait for test to complete
    runs-on: ubuntu-latest
    # ...

Conditional Execution

Use if: to skip jobs:

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    # ...

Advanced Configuration

Multiple Runners

For faster builds, configure multiple runners with labels:

# Register runner with label
act_runner register --labels linux,docker

# Use in workflow
jobs:
  build:
    runs-on: [linux, docker]

Self-Hosted Runner Requirements

Ensure runner has:

• Node.js 20+
• PostgreSQL client
• Docker (for Docker workflows)
• Git
• Build tools (gcc, make, etc.)

Matrix Builds

Test across multiple Node versions:

jobs:
  test:
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

Deployment Configuration

SSH Deployment

For SSH-based deployments, add to workflow:

- name: Deploy to production
  env:
    SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
  run: |
    mkdir -p ~/.ssh
    echo "$SSH_KEY" > ~/.ssh/id_rsa
    chmod 600 ~/.ssh/id_rsa
    ssh-keyscan ${{ secrets.DEPLOY_HOST }} >> ~/.ssh/known_hosts

    ssh ${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }} << 'EOF'
      cd /var/www/basil
      git pull
      docker-compose pull
      docker-compose up -d
    EOF

Docker Registry

Push images to private registry:

- name: Login to registry
  uses: docker/login-action@v3
  with:
    registry: ${{ secrets.DOCKER_REGISTRY }}
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_PASSWORD }}

Best Practices

1. Use secrets for sensitive data (never hardcode)
2. Pin action versions (@v4 instead of @latest)
3. Add timeout to long-running jobs
4. Use caching to speed up builds
5. Run critical tests on every PR
6. Schedule heavy tests (E2E, security) for off-peak hours
7. Monitor runner capacity and scale as needed
8. Keep workflows DRY using reusable workflows

Resources

• Gitea Actions Docs: https://docs.gitea.com/usage/actions
• GitHub Actions Docs: https://docs.github.com/en/actions (syntax compatible)
• Act Runner: https://gitea.com/gitea/act_runner
• Nektos Act (local testing): https://github.com/nektos/act

Support

For issues with:

• Gitea Actions: Check Gitea documentation and community forums
• This project's workflows: Open an issue in the repository
• Runner setup: Consult act_runner documentation

---

Last Updated: 2025-10-24 Version: 1.0