No description
  • Dockerfile 100%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-16 09:53:37 +01:00
.forgejo/workflows fix: gate reusable workflows on the ref, not on event_name 2026-11-16 09:52:13 +01:00
examples fix: gate reusable workflows on the ref, not on event_name 2026-11-16 09:52:13 +01:00
images/tools feat: add buf-check workflow for Protobuf repos to ensure generated code consistency 2026-11-07 20:37:35 +01:00
runner fix: ensure force_pull is true to maintain up-to-date tools image in config 2026-11-07 20:42:12 +01:00
buildkit.md fix: clarify push behavior based on ref rather than event in buildkit workflow 2026-11-07 21:59:42 +01:00
README.md fix: gate reusable workflows on the ref, not on event_name 2026-11-16 09:52:13 +01:00

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:repository token still gets a 404 on a private repo if the account is not in the org at all.
  • A token with write:package still 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.yml entscheidet über den Push nicht selbst aus dem Kontext. Der Aufrufer reicht source_event: ${{ forgejo.event_name }} und source_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 auf event_name prüfen. Statt forgejo.event_name == 'push' && forgejo.ref_name == 'main' genügt forgejo.ref_name == 'main' — ein Pull Request hat nie main als 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.yml repeats 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_sha gives each build an immutable registry.julscha.de/libs/tools:sha-<12> alongside :latest — but it is a manual step: pass tools_image: with that tag until the rebuild is fixed.
  • The scanner versions in images/tools/Dockerfile float (golang:1, golangci-lint:latest, trivy:latest). Deliberate for Trivy, whose value is its freshness; less obviously right for the Go toolchain.