forge-base

Reusable Docker base images, callable Forgejo workflows, justfile recipes, and tooling configs shared across personal projects on forge.jacquin.app.

Solo-friendly — every consumer (human or agent) inherits the same baseline without copy-paste drift.

Repo must stay public — Forgejo cross-repo uses: requires the callee to be publicly readable (no token-based cross-repo auth as of Forgejo 15.0).

What's in v0.2.0

Path	Purpose
docker/bun.Dockerfile	Bun + git + just + ca-certs base. Built + pushed to Forgejo container registry on tag push.
.forgejo/workflows/qa-bun.yml	Reusable workflow — Bun project QA pipeline (typecheck/lint/fmt-check/test). Caller uses: it.
.forgejo/workflows/build-bun-tarball.yml	Reusable workflow — single-arch build + package step for Bun release artifacts.
just/{shared,bun}.just	Reusable just recipes. Import via import 'shared.just' after subtree-pull.
husky/pre-push	Full QA gate (just qa) — blocks git push on test/typecheck failure.
tsconfig/base.json	Strict TypeScript baseline.
biome/base.json	Biome lint/format defaults.
.forgejo/workflows/release.yml	This repo's self-release pipeline — builds + publishes the Docker image on tag v*.
.forgejo/workflows/qa.yml	This repo's self-CI — validates justfile + Dockerfile + workflow YAML.

Planned for later versions:

• docker/{rust,python}.Dockerfile (v0.3)
• .forgejo/workflows/{qa-rust,build-rust-tarball,qa-python,build-python-tarball}.yml (v0.3)
• just/{rust,python}.just (v0.3)

Versioning

Tag every meaningful change. Downstream projects pin forge-base@vX.Y.Z. SemVer applies — bump major when a recipe contract or workflow input changes.

Consumption

Docker — remote ref

FROM forge.jacquin.app/charles/forge-base/bun:v0.2.0
COPY . .
RUN bun install
CMD ["bun", "run", "src/main.ts"]

CI — reusable workflow refs (Forgejo 15+)

.forgejo/workflows/qa.yml:

name: qa
on:
  push:
  pull_request:
    branches: [main]
jobs:
  qa:
    uses: charles/forge-base/.forgejo/workflows/qa-bun.yml@v0.2.0
    with:
      image_tag: v0.2.0

.forgejo/workflows/release.yml:

name: release
on:
  push:
    tags: [v*]
jobs:
  build-x86_64:
    uses: charles/forge-base/.forgejo/workflows/build-bun-tarball.yml@v0.2.0
    with:
      arch: x86_64
      image_tag: v0.2.0
      artifact_name: dist-x86_64
  build-aarch64:
    uses: charles/forge-base/.forgejo/workflows/build-bun-tarball.yml@v0.2.0
    with:
      arch: aarch64
      image_tag: v0.2.0
      artifact_name: dist-aarch64
  publish:
    # project-specific publish job (Forgejo release create, etc.)
    needs: [build-x86_64, build-aarch64]
    ...

Project still owns the publish job (release notes, optional Docker image build). The reusable workflows handle the standardized build/QA bits.

Pinning

@vX.Y.Z (tag) or @<sha> both work. Tags are mutable so SHA-pinning is safer for prod-critical pipelines; tags are fine for everything else and make Renovate-style auto-bumps trivial.

Justfile + tsconfig + biome — git subtree

git subtree add --prefix=.forge-base \
  https://forge.jacquin.app/charles/forge-base.git v0.2.0 --squash

Then in justfile:

import '.forge-base/just/shared.just'
import '.forge-base/just/bun.just'

In tsconfig.json:

{ "extends": "./.forge-base/tsconfig/base.json" }

In biome.json:

{ "extends": ["./.forge-base/biome/base.json"] }

In .husky/pre-push:

#!/usr/bin/env sh
exec sh .forge-base/husky/pre-push "$@"

Bump version: git subtree pull --prefix=.forge-base ... v0.3.0 --squash.

Justfile contract for downstream projects

Reusable workflows assume the caller's justfile exposes:

Recipe	Used by	Notes
ci-setup	qa-bun, build-bun-tarball	Install workspace deps (e.g. bun install --frozen-lockfile).
typecheck	qa-bun	bun x turbo run typecheck (or equivalent).
lint	qa-bun	bun x @biomejs/biome@^2 check .
fmt-check	qa-bun	bun x @biomejs/biome@^2 format .
test	qa-bun	bun x turbo run test
ci-build	build-bun-tarball	Build release artifacts into dist/.
ci-package	build-bun-tarball	Pack dist/ into dist/${PROJECT_NAME}-${VERSION}-${ARCH}-linux.tar.gz. Reads ARCH, VERSION, PROJECT_NAME env vars.

just/bun.just (in this repo) defines all of these. Import it directly via subtree, or copy/redefine in your project's justfile.

Repo conventions

Per global Forgejo Actions naming:

• Workflow names: qa (push + PR), release (tag v*)
• Job IDs: qa; for releases build-x86_64, build-aarch64, publish
• Architecture naming: x86_64 / aarch64 (Rust target-triple convention)

Container registry secret

The release workflow pushes images to Forgejo's container registry. Add a repo secret PACKAGE_TOKEN containing a Forgejo PAT with write:package scope. The workflow logs in as the repo owner.