78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
|
# CI/CD — what git actions trigger what
|
||
|
|
|
||
|
|
The pipeline is a single Forgejo Actions workflow,
|
||
|
|
[.forgejo/workflows/build.yml](../.forgejo/workflows/build.yml), triggered on every
|
||
|
|
push (`on: [push]`, which covers both branch and tag pushes). This document explains
|
||
|
|
which git action produces which outcome. For one-time host setup, the on-disk
|
||
|
|
layout, and manual deploy/rollback, see [INSTALL.md](INSTALL.md).
|
||
|
|
|
||
|
|
## Trigger behavior at a glance
|
||
|
|
|
||
|
|
| You push… | Build + test | Stage binary to host | Activate (go live) |
|
||
|
|
|---|:---:|:---:|:---:|
|
||
|
|
| any branch (no tag) | ✅ | — | — |
|
||
|
|
| a **release** tag `X.Y.Z` (e.g. `1.4.0`) | ✅ | ✅ | ✅ |
|
||
|
|
| a **pre-release** tag (anything else, e.g. `0.0.0a3`) | ✅ | ✅ | — |
|
||
|
|
|
||
|
|
- **Branch push** → builds and runs the full test suite, uploads the `hsa` binary as
|
||
|
|
a run artifact. Nothing touches the server. This is your PR / pre-merge gate.
|
||
|
|
- **Release tag** `X.Y.Z` → builds, tests, copies the binary to the host, and makes
|
||
|
|
it live (symlink swap + service restart).
|
||
|
|
- **Pre-release tag** → builds, tests, and copies the binary to the host, but does
|
||
|
|
**not** activate it. Use this to park a build on the server (QA, manual
|
||
|
|
activation) without flipping production.
|
||
|
|
|
||
|
|
The release-vs-pre-release decision is purely the tag name: the **Activate** step
|
||
|
|
runs only when the tag matches the regex `^[0-9]+\.[0-9]+\.[0-9]+$`. Note this means
|
||
|
|
a `v`-prefixed tag (`v1.4.0`) would build + stage but **not** activate — tag with
|
||
|
|
**bare numbers** (`1.4.0`).
|
||
|
|
|
||
|
|
## What each step does
|
||
|
|
|
||
|
|
1. **Checkout** — `git clone` of the pushed branch/tag (the runner doesn't use a
|
||
|
|
checkout action).
|
||
|
|
2. **Test** — `go test ./...` inside a `golang:1.26` container.
|
||
|
|
3. **Build** — static binary: `CGO_ENABLED=0 go build -buildvcs=false -ldflags "-s -w"`
|
||
|
|
(pure-Go SQLite, so no C toolchain; `-buildvcs=false` avoids the container's
|
||
|
|
dubious-ownership git error).
|
||
|
|
4. **Upload binary** — the `hsa` binary as a downloadable run artifact.
|
||
|
|
5. **Stage release** *(tags only)* — `scp` the binary to
|
||
|
|
`~/hsa-app/releases/hsa-app-V<tag>/hsa` on the host and `chmod +x` it.
|
||
|
|
6. **Activate release** *(release tags `X.Y.Z` only)* — `ln -sfn` the
|
||
|
|
`~/hsa-app/hsa` symlink to the new release and `systemctl --user restart hsa_app`.
|
||
|
|
Pre-release tags log "staged but not activated" and stop here.
|
||
|
|
|
||
|
|
## Cutting a release
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 1. land your change on main (push branch -> CI builds/tests -> merge)
|
||
|
|
# 2. tag and push:
|
||
|
|
git tag -a 1.4.0 -m "1.4.0 — <summary>"
|
||
|
|
git push origin 1.4.0
|
||
|
|
```
|
||
|
|
|
||
|
|
The tag push runs the whole pipeline through Activate. Watch it under the repo's
|
||
|
|
**Actions** tab; the **Activate release** step is the one that goes live. Roll back
|
||
|
|
by activating an older still-staged release (see [INSTALL.md](INSTALL.md)).
|
||
|
|
|
||
|
|
## Runner requirements
|
||
|
|
|
||
|
|
- One Forgejo `act_runner` registered with the **`shell`** label (`runs-on: shell`).
|
||
|
|
The job runs directly on the host, which therefore must have the **docker CLI**
|
||
|
|
available (the Test/Build steps run inside `golang:1.26` via `docker run`).
|
||
|
|
- The deploy steps `ssh`/`scp` from the runner host to the app host (they may be the
|
||
|
|
same machine). The app must run as a **user systemd service** named `hsa_app`,
|
||
|
|
reachable via `systemctl --user` — which requires `loginctl enable-linger` for the
|
||
|
|
deploy user (see [INSTALL.md](INSTALL.md)).
|
||
|
|
|
||
|
|
## Required repo configuration (Settings → Actions)
|
||
|
|
|
||
|
|
| Name | Kind | Purpose |
|
||
|
|
|---|---|---|
|
||
|
|
| `FORGEJO_SSH` | **Secret** | private SSH key authorized on the app host |
|
||
|
|
| `HSA_APP_HOST` | **Variable** | app host name / IP |
|
||
|
|
| `HSA_APP_USER` | **Variable** | SSH user that owns `~/hsa-app` and the user service |
|
||
|
|
|
||
|
|
If these are missing, branch pushes still build/test, but the Stage/Activate steps
|
||
|
|
fail on tags.
|