GitHub Deployment Bridge

A lightweight Kubernetes controller that bridges FluxCD reconciliations to the GitHub Deployments API.

When a Flux Kustomization or HelmRelease reconciles, the bridge inspects deployed container images, reads standard OCI labels (with optional Kubernetes annotation overrides), and reports the full GitHub Deployment lifecycle (queued → in_progress → success / failure) for the discovered repository and commit - with zero per-application mapping database.

How it works

flowchart TD
  Flux[Flux Kustomization / HelmRelease] --> Phase[Derive phase + discover inventory]
  Phase --> OCI[Fetch OCI labels]
  OCI --> Meta[Resolve metadata]
  Meta --> Auth[GitHub App auth]
  Auth --> Dep[Create Deployment + Status]
  Dep --> Cache[(SQLite cache)]

Loading

OCI labels

Label	Required	Example
org.opencontainers.image.source	yes*	https://github.com/example/backend
org.opencontainers.image.revision	yes*	0123456789abcdef
org.opencontainers.image.version	no	v1.8.4
org.opencontainers.image.title	no	backend
org.opencontainers.image.created	no	2026-07-25T12:00:00Z

*Unless overridden by a Kubernetes annotation. See docs/architecture.md.

Kubernetes annotations (opt-in)

Prefix: github-deployment-bridge.io/. Workloads must set auto-report=true to be reported; all other annotations are optional overrides. Full list: docs/architecture.md.

Install

Full guide (GitHub App permissions, secrets, PVC, Helm values, verify): Install · docs/install/.

Quick start with an existing Secret:

kubectl -n flux-system create secret generic github-deployment-bridge \
  --from-literal=app-id=123456 \
  --from-literal=installation-id=987654 \
  --from-file=private-key=./github-app.pem

helm upgrade --install github-deployment-bridge \
  oci://ghcr.io/roberteggl/charts/github-deployment-bridge \
  --version 1.4.1 \
  --namespace flux-system \
  --set github.existingSecret=github-deployment-bridge \
  --set config.clusterName=production-eu \
  --set config.environment=production

GitHub App (summary)

Permission	Access
Deployments	Read & Write
Contents	Read
Metadata	Read

PATs are not supported. Details: docs/install/github-app.md.

Configuration

Env vars and Helm mapping: docs/configuration/.

GitHub prominently exposes only environment_url and status log_url. Point config.logURLTemplate at Grafana Loki Explore, a Grafana dashboard, or another Flux/Kubernetes dashboard; enable config.logURLTemplateEscape for safe placeholder substitution. Copy-paste presets and Kustomization, HelmRelease, and monorepo examples are in Log URL placeholders.

PVC / SQLite at /data/cache.db deduplicates (owner, repo, environment, commitSHA, deploymentName) across restarts - see docs/install/persistence.md.

Observability

Endpoint	Purpose
/metrics	Prometheus metrics (unauthenticated HTTP)
/healthz	Liveness
/readyz	Readiness

Metrics include deployments_created_total, deployment_status_updates_total, deployment_failures_total, deployment_errors_total, deployment_duplicates_skipped_total, deployment_inactive_total, github_api_requests_total, github_api_failures_total, github_api_latency_seconds, github_installation_resolutions_total, and oci_requests_total.

Helm: optional serviceMonitor.enabled / prometheusRule.enabled for Prometheus Operator; restrict scrape peers with networkPolicy + metricsFrom (Metrics, Grafana, Runbook).

Official Grafana dashboard: deploy/grafana/github-deployment-bridge.json.

Image: ghcr.io/roberteggl/github-deployment-bridge:<version> (multi-arch amd64/arm64, Cosign-signed, SLSA-attested).

Verify artifacts: docs/releasing.md · Attestations

Development

make tidy test build

See CONTRIBUTING.md, docs/install/, docs/development.md, docs/architecture.md, and docs/releasing.md.

Non-goals

This project does not reconcile GitOps state, trigger deployments, run CI, or manage image automation. It only observes Flux reconciliations and synchronizes deployment lifecycle state into GitHub.

Licensing

This project follows the REUSE specification. Copyright and license information is declared per file via SPDX headers. The full Apache License 2.0 text lives in LICENSES/Apache-2.0.txt.