🚀 GitHub Action for GitOps

This GitHub Action can be used for our GitOps workflow. The GitHub Action will build and push the Docker image for your service and deploys the new version at your Kubernetes clusters.

Requirement

When you want to use this GitHub Action your GitHub repository should have a dev and master / main branch and it should use tags for releases.

• For the dev branch we will change the files specified under gitops-dev.
• For the master / main branch we will change the files specified under gitops-stage.
• For a new tag the files under gitops-prod will be used.

This GitOps setup should be the default for all your repositories. However, if you have a special case, you can leave gitops-dev, gitops-stage and gitops-prod undefined, then those steps will be skipped.

Usages

Build, Push and Deploy Docker Image

name: CDon: [ push ]jobs:
ci-cd:
name: Build, Push and Deployruns-on: ubuntu-24.04steps:
- name: Checkoutuses: actions/checkout@v6
- name: GitOps (build, push and deploy a new Docker image)uses: Staffbase/gitops-github-action@v7.1with:
docker-username: ${{ vars.HARBOR_USERNAME }}docker-password: ${{ secrets.HARBOR_PASSWORD }}docker-image: private/my-servicegitops-token: ${{ secrets.GITOPS_TOKEN }}gitops-dev: |- clusters/customization/dev/mothership/my-service/my-service-helm.yaml spec.template.spec.containers.redbook.imagegitops-stage: |- clusters/customization/stage/mothership/my-service/my-service-helm.yaml spec.template.spec.containers.redbook.imagegitops-prod: |- clusters/customization/prod/mothership/my-service/my-service-helm.yaml spec.template.spec.containers.redbook.image

Build and Push Docker Image

name: CDon: [ push ]jobs:
ci-cd:
name: Build and Pushruns-on: ubuntu-24.04steps:
- name: Checkoutuses: actions/checkout@v6
- name: GitOps (build and push a new Docker image)uses: Staffbase/gitops-github-action@v7.1with:
docker-username: ${{ vars.HARBOR_USERNAME }}docker-password: ${{ secrets.HARBOR_PASSWORD }}docker-image: private/my-service

Deploy Docker Image

name: CDon: [ push ]jobs:
ci-cd:
name: Deployruns-on: ubuntu-24.04steps:
- name: Checkoutuses: actions/checkout@v6
- name: GitOps (deploy a new Docker image)uses: Staffbase/gitops-github-action@v7.1with:
docker-image: private/my-servicegitops-token: ${{ secrets.GITOPS_TOKEN }}gitops-dev: |- clusters/customization/dev/mothership/my-service/my-service-helm.yaml spec.template.spec.containers.redbook.imagegitops-stage: |- clusters/customization/stage/mothership/my-service/my-service-helm.yaml spec.template.spec.containers.redbook.imagegitops-prod: |- clusters/customization/prod/mothership/my-service/my-service-helm.yaml spec.template.spec.containers.redbook.image

Deployment tracking annotations

By default (deployment-annotations: 'true'), whenever the action updates a GitOps file it stamps the following annotations onto the manifest's metadata.annotations:

Annotation	Value
deploy.staffbase.com/repositoryFullName	The source repository in owner/repo form ($GITHUB_REPOSITORY)
deploy.staffbase.com/commitSha	The commit SHA being deployed ($GITHUB_SHA)
deploy.staffbase.com/version	The image tag written to the GitOps repo — always the non-timestamped tag: dev-<short-sha> on dev, main-<short-sha> on main, master-<short-sha> on master, the version without the leading v on v* tag pushes, and the tag name on other tag pushes. See GitOps tag below

These keys mirror the Swarmia Deployment API field names and are read by flux-deployment-reporter to report deployments to Swarmia once Flux finishes reconciling. Set deployment-annotations: 'false' to skip them. The deploy.staffbase.com namespace is configurable via deployment-domain.

Deployment tracking labels

Enabled by default (deployment-labels: 'true'). The same three values are stamped onto the built Docker image as OCI labels, using reverse-DNS keys — the deployment-domain reversed (deploy.staffbase.com → com.staffbase.deploy):

Label	Value
com.staffbase.deploy.repositoryFullName	The source repository in owner/repo form ($GITHUB_REPOSITORY)
com.staffbase.deploy.commitSha	The commit SHA being deployed ($GITHUB_SHA)
com.staffbase.deploy.version	The non-timestamped GitOps tag (same value as the deploy.staffbase.com/version annotation)

Note: labels are baked in at build time, so they are only applied on builds. Release (v*) and custom-tag runs that retag an existing image instead of rebuilding (see Image tags) do not get fresh labels — the retagged image keeps the labels from the branch build it was promoted from. This feature is independent of the annotations above; enable either, both, or neither.

Inputs

Name	Description	Default
docker-registry	Docker Registry	registry.staffbase.com
docker-registry-api	Docker Registry API (used for retagging without pulling)	https://registry.staffbase.com/v2/
docker-image	Docker Image
docker-custom-tag	Docker Custom Tag to be set on the image
docker-tag-timestamp	Insert a UTC timestamp into dev/main/master branch tags (dev-<timestamp>-<short-sha>) to make them sortable for Flux image automation. Enabled by default; set to 'false' for the legacy <prefix>-<short-sha> format	true
docker-tag-keep-v-prefix	Keep the leading v on release (v*) tags (v1.2.3 → v1.2.3). Default strips it (v1.2.3 → 1.2.3)	false
docker-username	Username for the Docker Registry
docker-password	Password for the Docker Registry
docker-file	Dockerfile	./Dockerfile
docker-build-args	List of build-time variables
docker-build-secrets	List of secrets to expose to the build (e.g., key=string, GIT_AUTH_TOKEN=mytoken)
docker-build-secret-files	List of secret files to expose to the build (e.g., key=filename, MY_SECRET=./secret.txt)
docker-build-target	Sets the target stage to build like: "runtime"
docker-build-platforms	Sets the target platforms for build	linux/amd64
docker-build-provenance	Generate provenance attestation for the build	false
docker-disable-retagging	Disables retagging of existing images and run a new build instead	false
deployment-annotations	Stamp deployment-tracking annotations (deploy.staffbase.com/*) onto updated GitOps manifests. See Deployment tracking annotations	true
deployment-domain	Key namespace for deployment-tracking metadata. Used verbatim for annotation keys (<domain>/...) and reversed to reverse-DNS for label keys (com.staffbase.deploy.*)	deploy.staffbase.com
deployment-labels	Stamp deployment-tracking labels (com.staffbase.deploy.*) onto the built image. Only applied on builds, not on release/custom retags. See Deployment tracking labels	true
gitops-organization	GitHub Organization for GitOps	Staffbase
gitops-repository	GitHub Repository for GitOps	mops
gitops-user	GitHub User for GitOps	Staffbot
gitops-email	GitHub Email for GitOps	staffbot@staffbase.com
gitops-token	GitHub Token for GitOps
gitops-dev	Files which should be updated by the GitHub Action for DEV, must be relative to the root of the GitOps repository
gitops-stage	Files which should be updated by the GitHub Action for STAGE, must be relative to the root of the GitOps repository
gitops-prod	Files which should be updated by the GitHub Action for PROD, must be relative to the root of the GitOps repository
working-directory	The directory in which the GitOps action should be executed. The docker-file variable should be relative to working directory.	.

Outputs

Name	Description
docker-digest	Digest of the image
docker-tag	Tag of the image

Image tags & Flux image automation

The generated image tag depends on the Git ref:

Ref	Tag (default)	Tag (docker-tag-timestamp: 'false')	Floating tag
dev branch	dev-<utc-timestamp>-<short-sha>	dev-<short-sha>	dev
main branch	main-<utc-timestamp>-<short-sha>	main-<short-sha>	main
master branch	master-<utc-timestamp>-<short-sha>	master-<short-sha>	master
v* tag (prod)	the version with the v stripped, e.g. v2025.50.14 → 2025.50.14 (or kept with docker-tag-keep-v-prefix: 'true')	(unchanged)	latest
other branch	<short-sha> (not pushed)	(unchanged)	—

By default branch tags carry a YYYYMMDDHHMMSS (UTC) timestamp inserted before the SHA. This makes branch tags sortable so Flux image automation can pick the newest build — the Git SHA alone is not orderable. The short SHA is kept for traceability and Flux sorts on the timestamp only. Set docker-tag-timestamp: 'false' to fall back to the legacy <prefix>-<short-sha> shape.

Note: with the timestamp enabled (the default) the build also pushes the plain <prefix>-<short-sha> tag alongside the timestamped one. That stable per-commit tag is what the release step retags into the version tag and what the action writes to the GitOps repo (see GitOps tag), so it must continue to exist. It does not match the ^<prefix>-[0-9]+-[0-9a-f]+$ filter below, so Flux ignores it.

GitOps tag

The tag the action builds and pushes is the timestamped one (so Flux image automation can sort it). The tag the action writes to the external GitOps repo (gitops-dev/gitops-stage/gitops-prod files and the deployment annotations) is always the non-timestamped tag — the stable <prefix>-<short-sha> alias for branch builds, and the plain tag for v*/custom builds (which never carry a timestamp).

This is deliberate and not configurable. When the action runs across separate invocations — e.g. one step builds the image and a later step pushes and updates GitOps — each invocation recomputes a fresh timestamp, so the timestamped tag differs between them. The <prefix>-<short-sha> alias is deterministic, so the GitOps reference stays consistent and always points at an image that was actually pushed.

With the timestamp enabled, use one ImagePolicy per environment, filtering by prefix:

# dev (and likewise main-/master- for stage)spec:
imageRepositoryRef: { name: my-service }filterTags:
pattern: '^dev-(?P<ts>[0-9]+)-[0-9a-f]+$'extract: '$ts'policy:
numerical: { order: asc }
---
# prod — CalVer tags parse as SemVer (no zero-padding!)spec:
imageRepositoryRef: { name: my-service }policy:
semver: { range: '>=0.0.0' }

Note: the prod semver policy only works if CalVer parts are never zero-padded (2025.5.3, not 2025.05.03) — SemVer forbids leading zeros. Track the immutable *-<timestamp>-<sha> tags, not the floating dev/main tags, so deployments keep their provenance.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License

This project is licensed under the Apache-2.0 License - see the LICENSE.md file for details.

Staffbase GmbH Staffbase is an internal communications platform built to revolutionize the way you work and unite your company. Staffbase is hiring: jobs.staffbase.com GitHub | Website | Jobs

Releasing new versions

Go to the release overview page and publish the draft release with a new version number. Make sure to update the floating version commit.