ce-infra/docs/gitea-actions-guide.md

Gitea Actions — CI/CD Guide

What is this?

Gitea Actions is our built-in CI/CD system. It lets you automate tasks when things happen in a git repository — like running tests on every push, deploying a site when you merge to main, or running a script on a schedule.

If you've used GitHub Actions before, it's the same syntax.

How it works

sequenceDiagram
    participant Dev as Developer
    participant Gitea as Gitea
    participant Runner as Runner (box-runner)
    participant Container as Job Container

    Dev->>Gitea: Push code
    Gitea->>Runner: "There's a job to run"
    Runner->>Container: Spin up temporary container
    Container->>Container: Execute workflow steps
    Container-->>Runner: Results
    Runner-->>Gitea: Report status (pass/fail)
    Note over Container: Container is cleaned up
    Gitea-->>Dev: Show result in UI

Our runner (box-runner) runs on the same server as everything else. When a job triggers, it spins up a temporary Docker container, runs the steps, reports back, and cleans up. The runner itself is always running in the background, waiting for work.

Quick start

1. Create a workflow file

In any Gitea repository, create a file at .gitea/workflows/ with a .yml extension:

# .gitea/workflows/hello.yml
name: Hello World
on: [push]

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello from CI!"

2. Push it

git add .gitea/workflows/hello.yml
git commit -m "Add CI workflow"
git push

3. Check the result

Go to your repository on Gitea → Actions tab. You'll see the workflow run with its status.

Workflow syntax

When to run (triggers)

# Run on every push
on: [push]

# Run on push to main only
on:
  push:
    branches: [main]

# Run on pull request
on: [pull_request]

# Run on a schedule (cron syntax)
on:
  schedule:
    - cron: "0 2 * * *"  # Every day at 2 AM

# Run manually from the UI
on:
  workflow_dispatch:

Available runners

Label	What it is
ubuntu-latest	Ubuntu container (default choice)
ubuntu-24.04	Ubuntu 24.04 specifically
ubuntu-22.04	Ubuntu 22.04 specifically

Use these in runs-on:

jobs:
  my-job:
    runs-on: ubuntu-latest

Common steps

Check out the code:

steps:
  - uses: actions/checkout@v4

Run a shell command:

steps:
  - run: echo "Hello"

Run multiple commands:

steps:
  - run: |
      echo "Step 1"
      echo "Step 2"
      ls -la      

Use environment variables:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MY_VAR: "some value"
    steps:
      - run: echo $MY_VAR

Use secrets (set in Gitea UI under repo Settings → Actions → Secrets):

steps:
  - run: echo ${{ secrets.MY_SECRET }}

Practical examples

Run tests on every push

name: Test
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm test

Deploy static site on push to main

name: Deploy Site
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy via rsync
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan box.cloud-elves.eu >> ~/.ssh/known_hosts
          rsync -avz --delete site/ root@box.cloud-elves.eu:/opt/www/          

For this to work, add a DEPLOY_KEY secret in the repo settings containing a private SSH key that has access to the server.

Scheduled task (glorified cron)

name: Nightly Cleanup
on:
  schedule:
    - cron: "0 3 * * *"  # 3 AM daily

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Running nightly task..."
      # Add your actual commands here

Build and push a Docker image

name: Build Image
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t my-app:latest .
      - run: docker tag my-app:latest git.cloud-elves.eu/myorg/my-app:latest
      # Push to Gitea's container registry if enabled

Where to find things in the UI

What	Where
Workflow runs	Repository → Actions tab
Workflow files	Repository → .gitea/workflows/ directory
Secrets	Repository → Settings → Actions → Secrets
Runner status	Site Administration → Actions → Runners (admin only)

Tips

• Workflows live in your repo as code — version controlled like everything else
• Each push shows a status check (green tick or red cross) next to the commit
• You can re-run failed workflows from the Actions tab
• Use workflow_dispatch trigger if you want a "run manually" button in the UI
• Keep workflows simple — if it's getting complex, it probably belongs in a script that the workflow just calls