- Dockerfile 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| examples | ||
| images/tools | ||
| runner | ||
| buildkit.md | ||
| README.md | ||
ci-templates
Shared Forgejo Actions workflows for the Julscha repositories. Each workflow carries its own header comment with the full list of inputs; this page only says which one to pick and documents the mechanisms that span repositories.
Workflows
All of them are reusable (on: workflow_call). A consuming repo composes them in its
own .forgejo/workflows/ci.yml.
| File | For | Runs on |
|---|---|---|
.forgejo/workflows/buildkit.yml |
Building and pushing an OCI image | build |
.forgejo/workflows/go-scan.yml |
Go SAST + SCA: gosec, govulncheck | docker |
.forgejo/workflows/go-test.yml |
Go unit tests | docker |
.forgejo/workflows/trivy-scan.yml |
Lockfile SCA for Node, Python, anything | docker |
.forgejo/workflows/buf-check.yml |
Protobuf repos: lint, breaking changes, codegen drift | docker |
.forgejo/workflows/node-package.yml |
Node packages published to @julscha |
docker |
.forgejo/workflows/mkdocs-pages.yml |
MkDocs repos, strict build + rsync deploy | docker |
.forgejo/workflows/tools-image.yml is not reusable — it is the trigger workflow that
rebuilds registry.julscha.de/libs/tools weekly.
Ready-made callers for the common shapes are in examples/: go-service.yml,
go-multi-image.yml, node-app.yml, node-package.yml, mkdocs.yml. Copy one to
.forgejo/workflows/ci.yml in the consuming repo.
Calling them
on:
push:
branches: ['**']
pull_request:
jobs:
scan:
uses: libs/ci-templates/.forgejo/workflows/go-scan.yml@main
secrets: inherit
test:
uses: libs/ci-templates/.forgejo/workflows/go-test.yml@main
secrets: inherit
image:
needs: [scan, test]
if: ${{ !cancelled() && !failure() }}
uses: libs/ci-templates/.forgejo/workflows/buildkit.yml@main
secrets: inherit
ref: @main means a change here reaches every consumer on its next pipeline. There is
no staging copy, so test a workflow change against one repository before merging.
Two things that are easy to get wrong:
Do not put runs-on on the calling job. Forgejo expands a reusable workflow into
its inner jobs and schedules each on the label that workflow declares. A runs-on on
the caller breaks that.
if: ${{ !cancelled() && !failure() }} on the image job is not decoration. Scan
and test run on every push and pull request, but a job can still end up skipped (a
re-run of only the image, a caller-side if), and without it a needs: on a skipped
job would skip the image build too.
Secrets
Org secrets on core-app and libs, handed over with secrets: inherit. Both belong
to the ci-bot service account.
| Secret | Scope | Used by |
|---|---|---|
REGISTRY_TOKEN |
write:package |
buildkit.yml, node-package.yml |
MODULES_TOKEN |
read:repository, read:package |
go-scan.yml, go-test.yml, buf-check.yml, buildkit.yml, mkdocs-pages.yml, and every job that pulls the tools image |
PAGES_SSH_KEY, PAGES_KNOWN_HOSTS |
— | mkdocs-pages.yml deploy step only |
There are no instance-wide secrets in Forgejo, by design, so these live per org and are duplicated across the two.
The workflows cannot declare which secrets they need — see the Forgejo quirk below. What each one does when a secret is missing is therefore a runtime check, and that is the entire contract:
| Workflow | Missing secret |
|---|---|
buildkit.yml |
WARN and continue — unless push is on, then a hard error |
go-scan.yml, go-test.yml |
WARN and continue; a repo with only public deps still scans |
node-package.yml, mkdocs-pages.yml |
hard error before anything else runs |
trivy-scan.yml |
scans nothing private, but still needs MODULES_TOKEN to pull its own job container |
Every caller passes secrets: inherit, including the one calling
trivy-scan.yml. That is not redundant: container.credentials is evaluated
before the first step, so a job whose own work needs no secret still fails with
failed to handle credentials: password is empty when the caller withholds them.
ci-bot must be a member of both orgs, with Code: Read and
Packages: Write on its team. Two ways this bites, and neither looks like a
permission problem:
- A valid
read:repositorytoken still gets a 404 on a private repo if the account is not in the org at all. - A token with
write:packagestill cannot push if the team only grants Packages: Read.
Why a long-lived PAT and not the automatic job token
The obvious objection to REGISTRY_TOKEN is that Forgejo already mints a token
per job — the equivalent of GitLab's CI_JOB_TOKEN, scoped to the repository
and worthless once the job ends. A PAT is worse in every structural way: it
never expires, it is valid instance-wide, and it has to be kept in sync across
every org.
It was measured, not assumed. The job token is handed to the job (both
secrets.GITHUB_TOKEN and secrets.FORGEJO_TOKEN, 40 characters) and
authenticates as the triggering user. It reaches Forgejo's package middleware
and is turned away there:
POST https://registry.julscha.de/v2/libs/token-selftest/blobs/uploads/
401 Unauthorized: reqPackageAccess
So the token is valid but carries no package write permission — matching
forgejo#1296. A permissions: block does not help; the capability is missing,
not withheld. forgejo#3571 tracks giving the Actions token more power; when
that lands, buildkit.yml should prefer the job token and keep the PAT only
as the fallback for pushing into a foreign owner.
Until then the PAT stays, and the mitigation is scope rather than lifetime:
REGISTRY_TOKEN carries write:package and nothing else, MODULES_TOKEN
carries read scopes and nothing else, and no job is handed the push token when
it only needs to pull.
Pulling the tools image
The tools image is private, and the runner pulls a job container anonymously unless the job says otherwise. Forgejo answers an unauthenticated request for a private package with a 404, so the failure reads as a typo:
docker pull image=registry.julscha.de/libs/tools:latest username=
Error response from daemon: failed to resolve reference
"registry.julscha.de/libs/tools:latest": not found
Every job that runs in the tools image therefore carries:
container:
image: registry.julscha.de/libs/tools:latest
credentials:
username: ci-bot
password: ${{ secrets.MODULES_TOKEN }}
MODULES_TOKEN rather than REGISTRY_TOKEN: pulling needs read:package,
which it has, and nothing should hand a write:package token to a job that
only reads. Forgejo Runner v13 removed the old DOCKER_USERNAME /
DOCKER_PASSWORD secret fallback, so this block is the only supported route.
A re-run does not re-read a called workflow
Forgejo expands uses: into the inner jobs when the run is created.
Re-run all jobs re-runs that expansion, so a fix in libs/ci-templates does
not reach it — the old image name or input stays baked in, and it looks like
the fix never landed.
Every entrypoint therefore declares workflow_dispatch:, so a fresh run can be
started from the Actions tab without an empty commit.
Registry namespaces
The Forgejo registry addresses images as <host>/<owner>/<image>, and the
owner has to be an existing user or organisation. There is no implicit
namespace: pushing to an owner that does not exist fails at the blob upload,
after authentication has already succeeded, with
POST https://registry.julscha.de/v2/ci/tools/blobs/uploads/: 404 Not Found
which reads like a routing problem and is not one. The token endpoint issues a token without checking that the owner exists.
Hence registry.julscha.de/libs/tools rather than .../ci/tools — libs is
an org that exists, and it is where ci-templates lives. Images for the
application repos land under their own org, e.g.
registry.julscha.de/core-app/backend; buildkit.yml derives that from the
repository and lowercases it.
Runners
Two labels: docker for scans, tests and docs, build for image builds. The build
label additionally requires the rootless buildkitd sidecar and the ci-buildkit
volume — see runner/ for the compose stack and the host setup.
The workers are amd64 only. Multi-arch images are not possible without adding QEMU/binfmt first.
Vulnerability exceptions (go-scan)
govulncheck has no ignore flag, so go-scan.yml gates on its exit code and
compares the reported advisory IDs against an optional .govulncheck-allow file in
the service repository root.
flowchart TD
run[govulncheck] --> rc{findings?}
rc -->|no| nofile{allow file?}
nofile -->|no| pass[pass]
nofile -->|yes| stale[fail: exception no longer needed]
rc -->|yes| has{allow file?}
has -->|no| block[fail]
has -->|yes| cov{every ID listed?}
cov -->|no| block
cov -->|yes| due{review date passed?}
due -->|yes| expired[fail: re-assess]
due -->|no| pass
One exception per line, blank lines and # comments ignored:
<GO-ID> <review-by YYYY-MM-DD> <reason>
The gate is strict in both directions on purpose. An unlisted finding fails the job, and so does an exception that is no longer reported or whose review date has passed. An exception therefore cannot rot quietly — it expires into a pipeline failure that asks for a fresh decision.
Use it only where upgrading cannot help: an advisory with no fixed version on the
module path in use, or one whose vulnerable code the service does not reach. A
reachable finding with a published fix belongs in go.mod, not here.
Bump julscha-backend/internal/cve/dependencies.go alongside any library upgrade,
otherwise the scanner keeps reporting the old version.
The Go toolchain floor is a separate trap with its own explanation in the
go-scan.yml header. It is set per repository in go.mod, not here.
Private Go modules
Module paths have two segments after the host and match the Forgejo repo path exactly:
code.julscha.de/libs/go-app-kit
code.julscha.de/libs/go-agent-proto
go-get discovery compares case-sensitively, which is why the org is libs and not
Libs. A three-segment path or a capitalised one fails with "unrecognized import
path", not with an auth error — worth knowing, because it looks like a token problem.
Consumers set GOPRIVATE=code.julscha.de/*; the workflows write the .netrc entry.
Forgejo-Eigenheiten
continue-on-error muss ein literales Bool sein. GitHub Actions erlaubt dort einen
${{ }}-Ausdruck, Forgejo lehnt ihn beim Parsen ab — bevor irgendetwas ausgewertet
wird:
cannot unmarshal !!str `${{ for...` into bool
Der Lauf startet dann gar nicht, und die Meldung nennt die Zeile im aufgerufenen
Workflow, nicht im eigenen. go-scan.yml, go-test.yml und trivy-scan.yml regeln
die develop-Ausnahme deshalb im Skript: SOFT kommt als env: herein (dort sind
Ausdrücke erlaubt), der Exit-Code wird am Ende ausgewertet.
Dasselbe gilt für jedes andere bool- oder zahlentypisierte Feld, etwa
timeout-minutes. if: ist davon nicht betroffen — das ist ein String-Feld.
on: workflow_call kennt kein secrets:. Erlaubt sind dort nur inputs und
outputs; alles andere bricht beim Parsen:
workflow_call only supports keys "inputs" and "outputs", but key "secrets" was found
Damit gibt es kein required: true und keine Deklaration dessen, was ein Workflow
braucht. Die Secrets kommen trotzdem an — Forgejo übergibt dem Runner beim FetchTask
ohnehin alle — aber geprüft werden muss zur Laufzeit, im ersten Schritt. Auf der
Aufrufer-Seite ist jobs.<id>.secrets: inherit dagegen unterstützt und bleibt stehen.
In einem expandierten Workflow ist forgejo.event_name gleich workflow_call.
Forgejo expandiert uses: serverseitig in die inneren Jobs. Was dort — und in
einem if:, das auf den inneren Job übertragen wird — vom echten Auslöser
übrig bleibt, ist nicht push, sondern workflow_call. forgejo.ref_name und
forgejo.ref überstehen die Expansion dagegen unverändert.
Das ist besonders unangenehm, weil nichts fehlschlägt: ein Image wird gebaut und nicht gepusht, ein Job wird übersprungen — alles grün, nur ohne Ergebnis.
Zwei Konsequenzen, beide im Code umgesetzt:
buildkit.ymlentscheidet über den Push nicht selbst aus dem Kontext. Der Aufrufer reichtsource_event: ${{ forgejo.event_name }}undsource_ref: ${{ forgejo.ref }}durch, wo der echte Event noch sichtbar ist. Fehlen die, baut der Job und pusht nie.- Ein
if:am aufrufenden Job darf nicht aufevent_nameprüfen. Stattforgejo.event_name == 'push' && forgejo.ref_name == 'main'genügtforgejo.ref_name == 'main'— ein Pull Request hat niemainals Ref-Namen.
Jeder Job-Container braucht node. actions/checkout ist eine
JavaScript-Action und läuft mit dem node des Job-Containers. Ein schlankes
Tool-Image ohne Node scheitert, bevor der erste eigene Schritt läuft:
OCI runtime exec failed: exec: "node": executable file not found in $PATH
exitcode '127': command not found
Deshalb gehört ein Tool ins Tools-Image statt in einen eigenen Container —
koalaman/shellcheck-alpine, aquasec/trivy und Ähnliche bringen das Werkzeug
mit, aber kein Node. Die Alpine-Node-Images haben umgekehrt Node, aber kein
git; dort braucht es den „Ensure git"-Schritt, sonst fällt actions/checkout
auf einen GitHub-only API-Download zurück.
A failed module download looks like a code error
golangci-lint cannot tell a module it failed to fetch from a module that does
not compile. A dropped stream from proxy.golang.org therefore surfaces as a
typecheck finding pointing at an innocent import:
internal/config/config.go:6:2: could not import github.com/spf13/viper
(... golang.org/x/text@v0.42.0: read "https://proxy.golang.org/...":
stream error: INTERNAL_ERROR; received from peer) (typecheck)
go-scan.yml and go-test.yml therefore run go mod download in a step of
their own first, with three attempts. A network failure then says so, and a
flaky proxy costs a retry instead of a red pipeline.
The underlying cause is that the runner keeps no module cache between runs
(cache.enabled: false, and actions/cache would need the runner's cache
server reachable from each job's network). Every Go job pulls the full
dependency set. Worth revisiting if these jobs get slow.
Known rough edges
node-package.ymlrepeats its npm-registry step and its "Ensure git" shim verbatim in both jobs. Two occurrences do not justify a composite action, but do not let it become three.- The workflows consume the tools image as
:latest, so a broken weekly rebuild reaches every repo at once. Rolling back is possible —tag_shagives each build an immutableregistry.julscha.de/libs/tools:sha-<12>alongside:latest— but it is a manual step: passtools_image:with that tag until the rebuild is fixed. - The scanner versions in
images/tools/Dockerfilefloat (golang:1,golangci-lint:latest,trivy:latest). Deliberate for Trivy, whose value is its freshness; less obviously right for the Go toolchain.