vetrix/publish-artifact — Build and Publish Action

`vetrix/publish-artifact` — Build and Publish Action

Action: vetrix/publish-artifact@v1

Purpose

vetrix/publish-artifact is a bundled Vetrix CI action that builds a Docker image from your repository's workspace and pushes it to the Vetrix container registry for that repository. It runs as a Go binary backed by the vetrix/runner-publish runner image, which keeps registry credentials in memory only and never exposes them to the build environment.

Use this action whenever a pipeline job needs to produce a container image. The action emits the pushed manifest digest and a fully-qualified image reference as step outputs, so downstream jobs (such as a deploy step) can reference the exact, immutable image that was just built.

Inputs

User-supplied inputs

Input	Required	Default	Description
`image`	Yes	—	Image name without the registry host or `owner/repo` prefix. The Vetrix engine prepends the canonical registry host and the pipeline's `owner/repo` automatically. Example: `api-server`.
`tags`	No	`""`	Comma-separated list of tags to apply. When blank, the default tag strategy (`sha-<7char>,branch-<slug>`) is used. See Default tag strategy below.
`dockerfile`	No	`Dockerfile`	Path to the Dockerfile, relative to `context`.
`context`	No	`.`	Docker build context path, relative to the workspace root.
`build_args`	No	`""`	Build-time variables as newline-separated `KEY=VALUE` pairs. Passed as `--build-arg` flags and are not injected into the final image environment.
`target`	No	`""`	Multi-stage build target name (passed as `--target`). Leave blank to build the final stage.
`platforms`	No	`""`	Comma-separated platform list for cross-platform builds. Requires Docker buildx on the runner image. Example: `linux/amd64,linux/arm64`. Single-platform builds do not require buildx.
`overwrite`	No	`"false"`	Allow pushing to a tag that already exists in the registry. Set to `"true"` for mutable tags such as `latest` or branch-tracking tags.

System-injected inputs

The following inputs are templated and injected by the Vetrix engine before the runner starts. Do not set these manually — the engine will always override them.

Input	Description
`registry-url`	Fully-qualified registry host for the Vetrix instance.
`runner-token`	Short-lived, per-job scoped token used to authenticate the registry push.
`commit-sha`	Full 40-character commit SHA at pipeline trigger time.
`branch-name`	Branch name at pipeline trigger time.
`workflow-run-id`	UUID of the workflow run that scheduled this action.

Outputs

Output	Description
`image_digest`	OCI manifest digest of the primary pushed image, in the form `sha256:<hex>`. Uniquely identifies the exact image content, independent of mutable tags. Suitable for use in deployment manifests and attestation predicates.
`image_ref`	Fully-qualified reference for the primary tag: `{registry_host}/{owner}/{repo}/{image}:{primary_tag}`. The primary tag is the first tag in the resolved list.
`tags`	Comma-separated list of all tags that were successfully pushed. On partial failure, only the pushed tags are reported here.

Default tag strategy

When the tags input is blank (the default), the action applies two tags automatically:

Tag	Mutability	Purpose
`sha-<7char>`	Immutable — a new commit produces a new tag	Exact provenance; safe to pin in deployment manifests
`branch-<slug>`	Mutable — updated on every push to the branch	Latest build for that branch; useful for staging environments

The slug is derived from the branch name: lowercased, with / replaced by -, all non-[a-z0-9-] characters replaced by -, runs of - collapsed, and leading/trailing - stripped. Maximum 128 characters. For example, feature/New-Publish becomes feature-new-publish.

When you supply an explicit tags input, the default is bypassed entirely. The first tag in the list becomes the "primary" tag used for image_ref and image_digest.

Sample pipeline YAML

The following is a complete working .vetrix-ci.yml that builds a Node.js application and publishes a container image:

stages:
  - build
  - publish

build:
  stage: build
  image: node:20
  commands:
    - npm ci
    - npm run build

publish:
  stage: publish
  uses: vetrix/publish-artifact@v1
  with:
    image: my-app
    dockerfile: Dockerfile
    # tags defaults to sha-<commit>,branch-<branch>

To build for multiple platforms or use a non-default Dockerfile location:

publish:
  stage: publish
  uses: vetrix/publish-artifact@v1
  with:
    image: my-app
    dockerfile: docker/Dockerfile.production
    context: .
    platforms: linux/amd64,linux/arm64
    build_args: |
      NODE_ENV=production
      APP_VERSION=1.2.3
    target: production
    overwrite: "true"

Using output refs downstream

Reference the image_ref or image_digest outputs in a downstream job using the steps.<job-name>.outputs.<output> expression syntax:

stages:
  - publish
  - deploy

publish:
  stage: publish
  uses: vetrix/publish-artifact@v1
  with:
    image: my-app

deploy:
  stage: deploy
  needs: [publish]
  image: alpine:3.19
  commands:
    - echo "Deploying ${{ steps.publish.outputs.image_ref }}"
    - echo "Digest: ${{ steps.publish.outputs.image_digest }}"
    - ./scripts/deploy.sh "${{ steps.publish.outputs.image_ref }}"

Using image_digest in the deploy command pins the deployment to the exact image content rather than a mutable tag, which is the recommended practice for production deployments.

Troubleshooting

Authentication failed

The action could not authenticate to the registry. Verify that the pipeline's repository has the container registry enabled. An admin can check or enable this under the repository settings. The per-job token is scoped to the triggering repository — pipelines cannot push to a different repository's registry namespace.

Tag already exists (`overwrite: false`)

The registry returned a conflict error because the tag already exists and overwrite is set to its default value of false. Set overwrite: "true" in the with block for mutable tags such as latest or branch-tracking tags. Leave overwrite: "false" (the default) for immutable commit-SHA tags to prevent accidental content replacement.

Build failed

Build errors pass through as the Docker build process exit code. The action does not suppress or wrap docker build output — the full build log appears in the job log stream. Fix the Dockerfile or build context and re-run the pipeline. Common causes: missing build context files, unavailable base image, or a RUN command that exits non-zero.

Digest output is empty (exit code 4)

The push completed successfully but the action could not parse the manifest digest from the push output. This is a non-fatal condition: the image is in the registry and image_ref and tags outputs are still populated. The image_digest output will be an empty string. If your downstream jobs depend on image_digest, check the job log for the raw push output and open an issue with the Vetrix maintainers.