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

```mermaid
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:

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

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

### 2. Push it

```bash
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)

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

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

### Common steps

**Check out the code:**
```yaml
steps:
  - uses: actions/checkout@v4
```

**Run a shell command:**
```yaml
steps:
  - run: echo "Hello"
```

**Run multiple commands:**
```yaml
steps:
  - run: |
      echo "Step 1"
      echo "Step 2"
      ls -la      
```

**Use environment variables:**
```yaml
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):**
```yaml
steps:
  - run: echo ${{ secrets.MY_SECRET }}
```

## Practical examples

### Run tests on every push

```yaml
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

```yaml
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)

```yaml
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

```yaml
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