# Using CI on git.altricade.com (Forgejo Actions)

This is a self-hosted **Forgejo** git server with **Forgejo Actions** (CI/CD).
A shared runner is already set up and running on the server — **you do not need to
install or register anything.** Just add a workflow file to your repo and it runs.

> Forgejo Actions uses the same syntax as GitHub Actions, so most GitHub workflow
> examples work here with minor tweaks (mainly the `runs-on:` label — see below).

---

## Quick start

1. In your repo, create a file at:
   ```
   .forgejo/workflows/ci.yml
   ```
2. Paste a workflow (see examples below).
3. Commit & push.
4. Open your repo's **Actions** tab to watch it run.

Minimal example:
```yaml
name: CI
on: [push]
jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from CI"
```

---

## Important: `runs-on:` must match a runner label

The shared runner only provides these labels. Your `runs-on:` **must** be one of them,
or the job will never start (it'll sit "waiting for a runner"):

| Label            | Image it runs in            | Use for                                  |
|------------------|-----------------------------|------------------------------------------|
| `docker`         | `node:22-bookworm`          | General jobs, `docker` / `docker compose`, Node |
| `node`           | `node:22-bookworm`          | Node projects                            |
| `go`             | `golang:1.23-bookworm`      | Go projects                              |
| `ubuntu-latest`  | `catthehacker/ubuntu:act-22.04` | GitHub-compatible workflows (heavier image) |

**Tip:** prefer `docker`, `node`, or `go` — they use small images that pull fast.
Use `ubuntu-latest` only if a workflow really needs the full GitHub-style environment
(its image is ~2 GB and slow to download the first time).

---

## Examples

### Go project
```yaml
name: Go CI
on: [push]
jobs:
  test:
    runs-on: go
    steps:
      - uses: actions/checkout@v4
      - run: go version
      - run: go build ./...
      - run: go test ./...
```

### Node project
```yaml
name: Node CI
on: [push]
jobs:
  test:
    runs-on: node
    steps:
      - uses: actions/checkout@v4
      - run: node --version
      - run: npm ci
      - run: npm test
```

### Docker / docker compose build
```yaml
name: Build
on: [push]
jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: docker --version
      - run: docker compose build
```
> The runner has access to Docker, so `docker` and `docker compose` commands work
> inside jobs.

---

## Good to know

- **First run of any new image is slow** — the runner downloads the job image once,
  then caches it on the server. Later runs are fast.
- **The runner is shared and capped at 1 concurrent job.** If we both push at the same
  time, jobs queue and run one after another. That's expected on this server.
- **Triggers:** `on: [push]` runs on every push. You can also use
  `on: [pull_request]`, schedules, manual `workflow_dispatch`, etc. — same as GitHub Actions.
- **Where things live:** workflow files go in `.forgejo/workflows/` in each repo.
- **Actions like `actions/checkout@v4`** are fetched from the public Forgejo actions
  registry the first time; also cached after.

---

## If a job doesn't start

- Check `runs-on:` is exactly one of: `docker`, `node`, `go`, `ubuntu-latest`.
- Check the **Actions** tab of the repo for the run and its logs.
- If it's stuck "waiting", the label probably doesn't match, or the shared runner is
  busy with another job (wait for it to finish).

---

## Notes for an LLM helping with this

- This is **Forgejo Actions** (not GitHub Actions, not GitLab CI). Syntax is
  GitHub-Actions-compatible; workflow files live in `.forgejo/workflows/*.yml`.
- Jobs run in **Docker containers** on a shared self-hosted runner.
- Valid `runs-on:` values are limited to the runner's registered labels:
  `docker` and `node` → `node:22-bookworm`, `go` → `golang:1.23-bookworm`,
  `ubuntu-latest` → `catthehacker/ubuntu:act-22.04`. Do **not** invent other labels.
- The runner has the Docker socket available, so `docker` / `docker compose` work in jobs.
- Concurrency is capped at 1; assume no parallelism across jobs.