This release brings clearer deployment status reporting, optional cleanup for unused source caches, and faster Git mirror operations. Please review the upgrade notes below for changes that may affect custom health checks, GitHub App status reporting, Prometheus queries, or stack cleanup.
Highlights
- Legacy Git stack recreation: Managed legacy stacks can now be recreated directly onto an artifact of the exact deployed commit, exported from the cached mirror when needed. No stop-first step or branch-tip deploy is required. See Artifact Storage.
- Richer deployment feedback: Status reporting now distinguishes queued, skipped, and timed-out deployments where supported, and shows the active deployment phase. See Commit status reporting
- Opt-in source-cache cleanup: Reclaim unused Git mirrors, submodule caches, and artifacts after a retention period. It preserves
live/data. Enable it in Compose:See source GC settings and what it removes.environment: SOURCE_GC_ENABLED: "true"
- Faster Git mirrors: Mirrors compact automatically once they exceed 32 packfiles to reduce cold-read overhead; on-demand compaction is also available through the REST API or MCP. See Git mirror compaction and On-demand compaction.
- Storage metrics: New Prometheus metrics expose mirror size and garbage-collection results. See metrics docs.
⚠️ Upgrade notes (check if applicable)
Custom health checks
The image now uses a dedicated, smaller /healthcheck binary for each health checks. A custom Compose healthcheck.test overrides the image default.
Action: If you set it to test: ["CMD", "/doco-cd", "healthcheck"], remove the override or change it to test: ["CMD", "/healthcheck"].
See the health check docs.
Stack cleanup
Destroying a stack now preserves its shared source directory so it cannot remove data used by another stack.
Important
destroy.remove_dir is now deprecated and ignored. See destroy settings docs.
Action: If you relied on that setting to reclaim unused source caches, enable source GC (disabled by default). See Destroy settings and Source GC settings
GitHub App status reporting
When deployment status reporting is enabled with GitHub App authentication, doco-cd now reports through GitHub Checks instead of commit statuses. Checks are separate from commit statuses in branch protection and require the App permission.
Action: Grant Checks: Read and write, approve the installation permission update, and review any required branch-protection checks. Token-based GitHub authentication continues to use commit statuses.
Prometheus queries
To reduce histogram series and scrape overhead, deployment_stage_duration_seconds no longer includes the deployment or context labels. Per-deployment timing remains available as deployment_duration_seconds.
Action: Remove deployment/context label filters or groupings from queries on the stage-duration histogram, or use the per-deployment metric.
See metrics docs.
What's Changed
🚨 Breaking Changes
- perf(metrics)!: drop deployment and context labels from the stage duration histogram by @kimdre in #1986
✨ Features
- feat(commitstatus): report native queued, skipped and timed-out deployment states by @kimdre in #1936
- feat(commitstatus): show the current deployment phase while deploying by @kimdre in #1940
- feat(gc): add opt-in garbage collector for unused source stores by @kimdre in #1988
🌟 Improvements
- perf(git): cache GitHub App installation lookups by @kimdre in #1939
- perf(git): compact bare mirror packfiles after fetch by @kimdre in #1946
- perf(git): look up short commit hashes in pack indexes by @kimdre in #1947
- perf(stages): walk deployment ancestry newest commit first by @kimdre in #1948
- perf(stages): skip notification commit lookups that are not delivered by @kimdre in #1951
- perf(git): reuse buffers across packs during mirror compaction by @kimdre in #1956
- perf(git): skip fetching submodule commits already in their mirror by @kimdre in #1957
- perf(store): skip publishing a git artifact another job just published by @kimdre in #1958
- feat(metrics): report git mirror size and artifact gc results by @kimdre in #1960
- chore(gc): log repositories skipped because they are in use by @kimdre in #1970
- feat(api): compact git mirrors on demand by @kimdre in #1974
- perf(healthcheck): reduce healthcheck startup cost by @kimdre in #1984
- perf(metrics): reuse a long-lived gzip writer for /metrics by @kimdre in #1985
- perf(healthcheck): run a separate small healthcheck binary in the image by @kimdre in #1989
- fix: migrate legacy Git stacks on recreate by @kimdre in #1993
🐛 Bug Fixes
- test: fix data races in parallel webhook and reconciliation tests by @kimdre in #1937
- fix(git): skip GitHub App auth for gist remotes by @kimdre in #1938
- fix(git): preserve Github App installation cache provenance by @kimdre in #1941
- fix(stages): enforce dwell per deployment phase by @kimdre in #1942
- fix(metrics): extend duration histogram buckets and instrument mirror reads by @kimdre in #1945
- fix(git): rebuild cross-pack deltas from the copied entry during compaction by @kimdre in #1954
- fix(notification): time out Apprise requests after 30 seconds by @kimdre in #1949
- fix(stages): post commit statuses for the published revision by @kimdre in #1950
- fix(git): group mirror compaction log fields and log readable durations by @kimdre in #1955
- fix(git): sync pack directory before removing replaced packs by @kimdre in #1961
- fix(migration): log which containers keep legacy checkout files by @kimdre in #1972
- fix(git): report all git mirrors in the pack metrics by @kimdre in #1973
- fix(storage): harden mirror compaction and discovery by @kimdre in #1975
- fix(destroy): keep shared source directories when destroying a stack by @kimdre in #1977
- fix(auto-discovery): discover and clean up stacks from published artifacts by @kimdre in #1978
- fix(destroy): match OCI and repository_url sources when destroying and cleaning up stacks by @kimdre in #1979
- fix(stages): allow cached preflight for stacks with host bind mounts by @kimdre in #1987
📦 Dependencies
- fix(deps): update module github.com/prometheus/common to v0.72.0 by @renovate[bot] in #1934
- chore(deps): update docker/dockerfile:1 docker digest to 4edf897 by @renovate[bot] in #1944
- chore(deps): update docker:29-dind docker digest to 7dcdfc4 by @renovate[bot] in #1943
- chore(deps): update golang:1.27.1 docker digest to e0174e5 by @renovate[bot] in #1964
- chore(deps): update gcr.io/distroless/base-debian13 docker digest to 389cad2 by @renovate[bot] in #1963
- chore(deps): update dependency zensical to v0.0.67 by @renovate[bot] in #1966
- chore(deps): update docker/buildx-bin docker tag to v0.37.2 by @renovate[bot] in #1967
- fix(deps): update module github.com/docker/cli to v29.8.2+incompatible by @renovate[bot] in #1968
- fix(deps): update module github.com/go-git/go-billy/v5 to v5.9.2 by @renovate[bot] in #1969
- fix(deps): update module github.com/go-git/go-git/v5 to v5.19.3 by @renovate[bot] in #1982
- fix(deps): update module github.com/moby/buildkit to v0.33.1 by @renovate[bot] in #1983
- chore(deps): update dependency zensical to v0.0.68 by @renovate[bot] in #1991
- fix(deps): update module github.com/moby/moby/api to v1.56.1 by @renovate[bot] in #1992
📚 Miscellaneous
Full Changelog: v0.123.0...v0.124.0