133 lines
4.2 KiB
Markdown
133 lines
4.2 KiB
Markdown
# 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.
|