README.md

gha-workflows

This repository contains reusable GitHub Workflows and Composite Actions shared across the Flux repositories.

Workflows

Release Flux controller

The controller-release workflow automates the release of Flux controllers by performing the following steps:

• Builds multi-arch images for linux/amd64, linux/arm64 and linux/arm/v7 with Docker.
• Generates SBOMs for each architecture with Syft.
• Pushes the images to ghcr.io/fluxcd and docker.io/fluxcd.
• Signs the images with Cosign and GitHub OIDC.
• Creates a GitHub Release with GoReleaser.
• Outputs metadata for SLSA attestations.

Example usage:

name: release
on:
  push:
    tags: [ 'v*' ]
  workflow_dispatch:
    inputs:
      tag:
        description: 'image tag prefix'
        default: 'rc'
        required: false
jobs:
  release:
    permissions:
      contents: write # for creating the GitHub release.
      id-token: write # for creating OIDC tokens for signing.
      packages: write # for pushing and signing container images.
    uses: fluxcd/gha-workflows/.github/workflows/controller-release.yaml@vX.Y.Z
    with:
      controller: ${{ github.event.repository.name }}
      release-candidate-prefix: ${{ github.event.inputs.tag }}
    secrets:
      github-token: ${{ secrets.GITHUB_TOKEN }}
      dockerhub-token: ${{ secrets.DOCKERHUB_TOKEN }}

3rd-party actions used:

• docker/setup-qemu-action
• docker/setup-buildx-action
• docker/login-action
• docker/metadata-action
• docker/build-push-action
• sigstore/cosign-installer
• anchore/sbom-action
• goreleaser/goreleaser-action

Outputs:

• release-digests: Release artifacts digests compatible with SLSA
• image-name: Published container image name (without the registry)
• image-digest: Published container image digest

Release Flux CLI Plugin

The cli-plugin-release workflow automates the release of Flux CLI plugins (Go binary plus container image) by performing the following steps:

• Publishes the GitHub release with GoReleaser, including the Go binary archives and checksums, when run on a version tag.
• Attests the release artifacts with GitHub Attestations for SLSA provenance, when run on a version tag.
• Builds a multi-arch image for linux/amd64 and linux/arm64 with Docker.
• Pushes the image to ghcr.io tagged with the git tag and latest, or with a release candidate prefix and short commit SHA when run on a branch.
• Signs the image with Cosign and GitHub OIDC.

Inputs:

• go-version (string, required): Go version to set up for the GoReleaser job.
• release-candidate-prefix (string, default rc): Image tag prefix used when the workflow runs on a branch.

Example usage:

name: release
on:
  push:
    tags: [ 'v*' ]
  workflow_dispatch:
    inputs:
      tag:
        description: 'image tag prefix'
        default: 'rc'
        required: true
jobs:
  release:
    permissions:
      contents: write # for creating the GitHub release.
      id-token: write # for creating OIDC tokens for signing.
      attestations: write # for GitHub Attestations.
      artifact-metadata: write # for GitHub SLSA provenance.
      packages: write # for pushing and signing container images.
    uses: fluxcd/gha-workflows/.github/workflows/cli-plugin-release.yaml@vX.Y.Z
    with:
      go-version: 1.25.x
      release-candidate-prefix: ${{ github.event.inputs.tag }}
    secrets:
      github-token: ${{ secrets.GITHUB_TOKEN }}

3rd-party actions used:

• anchore/sbom-action
• actions/attest
• docker/setup-qemu-action
• docker/setup-buildx-action
• docker/login-action
• docker/metadata-action
• docker/build-push-action
• goreleaser/goreleaser-action
• sigstore/cosign-installer

Backport to Release Branches

The backport workflow automates the backporting of merged pull requests to release branches based on labels in the format backport:release/semver (e.g. backport:release/v2.0.x). If a cherry-pick conflicts, the workflow opens a draft pull request with the conflict committed for manual resolution.

Example usage:

name: backport
on:
  pull_request_target:
    types: [closed, labeled]
jobs:
  backport:
    permissions:
      contents: write # for reading and creating branches.
      pull-requests: write # for creating pull requests against release branches.
    uses: fluxcd/gha-workflows/.github/workflows/backport.yaml@vX.Y.Z
    secrets:
      github-token: ${{ secrets.GITHUB_TOKEN }}

3rd-party actions used:

• korthout/backport-action

Code Scanning and License Validation

The code-scan workflow analyzes the code for security vulnerabilities using CodeQL and validates the licenses of the dependencies using FOSSA.

Example usage:

name: code-scan
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  analyze:
    permissions:
      contents: read # for reading the repository code.
      security-events: write # for uploading the CodeQL analysis results.
    uses: fluxcd/gha-workflows/.github/workflows/code-scan.yaml@vX.Y.Z
    secrets:
      github-token: ${{ secrets.GITHUB_TOKEN }}
      fossa-token: ${{ secrets.FOSSA_TOKEN }}

The CodeQL analysis uploads the results to GitHub Code Scanning Alerts, and the FOSSA analysis uploads the results to the FOSSA dashboard.

3rd-party actions used:

• fossas/fossa-action

CVE Scan

The cve-scan workflow scans Go modules for known vulnerabilities using govulncheck.

Example usage:

name: cve-scan
on:
  workflow_dispatch:
  schedule:
    - cron: "0 8 * * 1" # every Monday at 8 AM (UTC)
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  govulncheck:
    uses: fluxcd/gha-workflows/.github/workflows/cve-scan.yaml@vX.Y.Z

3rd-party actions used:

• golang/govulncheck-action

Update fluxcd/pkg Dependencies

The upgrade-fluxcd-pkg workflow automates updating fluxcd/pkg module dependencies in Flux controller repositories by performing the following steps:

• Checks out the caller repository and fluxcd/pkg at the main branch.
• Builds and runs the flux-tools bump command to update go.mod with the latest fluxcd/pkg module versions.
• Runs make tidy to tidy Go modules (non-blocking — a failure is noted in the PR body).
• Opens a pull request with the dependency changes.

Inputs:

• pre-release-pkg (boolean, default false): Temporary flag for Flux 2.8 — uses the flux/v2.8.x pkg branch for main branches because the pkg release branch was cut before the Flux distribution release. Remove this input once Flux 2.8.0 is released.

Example usage:

name: upgrade-fluxcd-pkg

on:
  workflow_dispatch:
    inputs:
      pre-release-pkg:
        description: >-
          Temporary flag for Flux 2.8: use the flux/v2.8.x pkg branch for main branches
          because the pkg release branch was cut before the Flux distribution release.
          Remove this input once Flux 2.8.0 is released.
        required: false
        default: false
        type: boolean

jobs:
  upgrade-fluxcd-pkg:
    uses: fluxcd/gha-workflows/.github/workflows/upgrade-fluxcd-pkg.yaml@vX.Y.Z
    with:
      pre-release-pkg: ${{ inputs.pre-release-pkg }}
    secrets:
      github-token: ${{ secrets.BOT_GITHUB_TOKEN }}

3rd-party actions used:

• peter-evans/create-pull-request

Sync Repository Labels

The labels-sync workflow synchronizes the standard and custom labels to the current repository.

Example usage:

name: sync-labels
on:
  workflow_dispatch:
  push:
    branches: [ main ]
    paths:
      - .github/labels.yaml
jobs:
  sync-labels:
    permissions:
      contents: read # for reading the labels file.
      issues: write # for creating and updating labels.
    uses: fluxcd/gha-workflows/.github/workflows/labels-sync.yaml@vX.Y.Z
    with:
      labels-file: .github/labels.yaml
    secrets:
      github-token: ${{ secrets.GITHUB_TOKEN }}

3rd-party actions used:

• EndBug/label-sync

Composite Actions

Setup Kubernetes

The setup-kubernetes composite action configures the GitHub runner to build and test Flux controllers with Kubernetes Kind clusters.

Inputs:

• go-version (string, required): Go version to set up.
• kind-version (string, optional): Kind version to set up.
• cluster-name (string, optional): Name of the kind cluster.
• kind-config (string, optional): Path to a kind cluster configuration file.
• skip-checkout (boolean, optional, default false): Skip checking out the repository when the caller has already run checkout. Useful for generating dynamic kind configs or spinning up multiple clusters in a single job.
• skip-tools (boolean, optional, default false): Skip the toolchain setup steps (Kustomize, QEMU, Buildx, Go) and only create the kind cluster. Useful when spinning up a second or third cluster in a single job after the tools have already been set up by a prior run.

Example usage:

name: e2e
on:
  pull_request:
  push:
    branches: [ main ]
jobs:
  kind:
    runs-on: ubuntu-latest
    permissions:
      contents: read # for reading the repository code.
    steps:
      - name: Test suite setup
        uses: fluxcd/gha-workflows/.github/actions/setup-kubernetes@vX.Y.Z
        with:
          go-version: 1.25.x
          kind-version: v0.30.0
      - name: Run tests
        run: make test

To generate dynamic kind configs or run against multiple clusters in a single job, check out the repository once and reuse the toolchain. The first invocation sets up the tools and creates a cluster; each subsequent invocation sets skip-checkout: true and skip-tools: true to only create an additional cluster:

name: e2e-multicluster
on:
  pull_request:
  push:
    branches: [ main ]
jobs:
  kind:
    runs-on: ubuntu-latest
    permissions:
      contents: read # for reading the repository code.
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Generate kind configs
        run: ./hack/gen-kind-configs.sh # writes /tmp/kind-cluster-1.yaml, /tmp/kind-cluster-2.yaml
      - name: Setup tools and cluster 1
        uses: fluxcd/gha-workflows/.github/actions/setup-kubernetes@vX.Y.Z
        with:
          go-version: 1.25.x
          cluster-name: cluster-1
          kind-config: /tmp/kind-cluster-1.yaml
          skip-checkout: true
      - name: Setup cluster 2
        uses: fluxcd/gha-workflows/.github/actions/setup-kubernetes@vX.Y.Z
        with:
          go-version: 1.25.x
          cluster-name: cluster-2
          kind-config: /tmp/kind-cluster-2.yaml
          skip-checkout: true
          skip-tools: true
      - name: Run tests
        run: make test

3rd-party actions used:

• docker/setup-qemu-action
• docker/setup-buildx-action
• helm/kind-action

Contributing

• The workflows must be placed in the .github/workflows directory and the filenames must be in the format <my-workflow>.yaml. The filename must match the workflow name.
• All workflows requiring repository access must expose a github-token secret input.
• The repo permissions must be set in the workflow file, and not rely on the default permissions.
• All the actions used in workflows must be pinned to a commit SHA (Dependabot is configured to keep them up to date).
• The usage of third-party actions should be limited to well-known actions with a good security track record.
• Changed to workflows should be tested in a fork before opening a pull request, especially those that trigger on push tag events.

Releasing new versions

To release a new version of the workflows, push a signed git tag with the version number (e.g. v1.2.3).

Dependabot is configured in the Flux controllers repositories to keep the workflows up to date with the latest released version.