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.