#Install in a cluster

Install GitHub Deployment Bridge with Helm alongside FluxCD: GitHub App, secrets, persistence, and verification.

#Prerequisites

• A Kubernetes cluster with FluxCD installed (Kustomization CRDs; HelmRelease CRDs if you want Helm reporting)
• Helm 3
• A GitHub App (see GitHub App setup) installed on the repositories you deploy
• Workload images that carry the required OCI labels (below), or equivalent github-deployment-bridge.io/* annotations

The bridge is an observer only. It does not reconcile GitOps state or mutate workloads. Install it in a namespace that can watch Flux Kustomization and HelmRelease resources (commonly flux-system).

HelmRelease inventory (required for image discovery) needs Flux ≥ 2.8 / helm-controller ≥ 1.5; older clusters simply skip HelmReleases with empty inventory.

#Required OCI labels

Bake these into each workload image so the bridge can resolve the GitHub repository and commit. Only two labels are required:

*Required unless overridden by the matching Kubernetes annotation (github-deployment-bridge.io/repository / commit). Workloads that use annotations must also set auto-report=true.

LABEL org.opencontainers.image.source="https://github.com/example/backend" \
      org.opencontainers.image.revision="0123456789abcdef"

Full precedence and annotation list: Metadata resolution.

#Steps

1. GitHub App setup
2. Secrets
3. PVC
4. Install with Helm
5. Verify

Optional: Private image registries · Uninstall · Artifact Hub