107 lines
3.8 KiB
Markdown
107 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
- 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
|
|
|
|
```text
|
|
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:
|
|
|
|
```dockerignore
|
|
**
|
|
!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:
|
|
|
|
```text
|
|
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`.
|