build-runner-image-action/README.md

Build Runner Image Action

A reusable composite action for Gitea Actions that builds a Docker runner image, runs project-specific verification commands, and publishes both an immutable Git revision tag and latest to a private Gitea Container Registry.

The action is hosted on Gitea and does not use GitHub. Call it with an absolute URL, which Gitea requires for actions hosted outside the configured default action source:

- name: Build, verify, and publish image
  uses: https://mahgit.ir/MeghdadFadaee/build-runner-image-action@v1
  with:
    registry: mahgit.ir
    image: mahgit.ir/example/project-runner
    source-url: https://mahgit.ir/example/project
    registry-username: ${{ secrets.REGISTRY_USERNAME }}
    registry-token: ${{ secrets.REGISTRY_TOKEN }}
    verify-commands: |
      docker run --rm "$IMAGE_REF" node --version
      docker run --rm "$IMAGE_REF" python3 --version

IMAGE_REF is available only to verify-commands and contains the immutable candidate image reference. The action publishes latest only after every verification command succeeds.

Default caller layout

project/
├── .dockerignore
├── requirements.lock
└── .gitea/workflows/build-runner-image.yml

The caller does not need a Dockerfile. Use this .dockerignore so the root build context sends only the dependency lock to Docker:

**
!requirements.lock

If requirements-file points somewhere else, update the exception to include that path.

Inputs

Input	Required	Default	Description
registry	Yes	-	Registry hostname
image	Yes	-	Fully qualified image name without a tag
base-image	No	Gitea-hosted node-20-bookworm	Base image override
context	No	.	Docker build context
requirements-file	No	requirements.lock	Lock path relative to the context
dockerfile	No	Shared Dockerfile	Optional caller Dockerfile override
source-url	Yes	-	OCI source-label URL
registry-username	Yes	-	Gitea registry username
registry-token	Yes	-	PAT with package Read and Write permission
verify-commands	No	Empty	Trusted shell commands using IMAGE_REF

Outputs

Output	Description
image	Image name without a tag
revision	Twelve-character Git revision
revision_tag	Immutable published image reference
latest_tag	Published latest image reference

Runner requirements

• The caller must check out its repository before invoking this action.
• The default Dockerfile expects a fully pinned requirements.lock at the build-context root.
• The job container must be Debian-based or already include a Docker client.
• The Docker daemon socket must be available to the job container.
• The runner should use container.force_pull: true.
• Only trusted repositories should use a runner with Docker socket access.

The action installs the Docker client only when it is absent. It sends the registry token through standard input, logs out on exit, builds with --pull, sets OCI revision/source labels, verifies the candidate, then publishes the immutable and moving tags.

The default Dockerfile lives at runner-image/Dockerfile in this action. It installs the shared Debian, Git, Python, virtual-environment, and timezone dependencies. A caller can provide requirements-file for a differently named lock inside its build context, or dockerfile when it needs different system packages.

The default base is:

mahgit.ir/meghdadfadaee/build-runner-image-base:node-20-bookworm

Use base-image only when a project needs a different base.

Versioning

Create immutable releases such as v1.0.0 and move the major v1 tag only for backward-compatible releases. Caller workflows should use @v1 rather than @main.