diff --git a/.github/workflows/chart.yaml b/.github/workflows/chart.yaml index 5d7a99d34..6f7fef306 100644 --- a/.github/workflows/chart.yaml +++ b/.github/workflows/chart.yaml @@ -9,7 +9,7 @@ name: Publish Helm Chart # stale chart fails the PR, not the release. # # Users then install with: -# helm install deer-flow oci://ghcr.io/${{ owner }}/deer-flow --version +# helm install deer-flow oci://ghcr.io/${{ owner }}/charts/deer-flow --version on: push: @@ -83,5 +83,5 @@ jobs: run: | for pkg in ./packages/*.tgz; do echo "--- pushing $pkg" - helm push "$pkg" oci://ghcr.io/${{ github.repository_owner }} + helm push "$pkg" oci://ghcr.io/${{ github.repository_owner }}/charts done diff --git a/.github/workflows/nightly.yaml b/.github/workflows/nightly.yaml index 234166339..583c25763 100644 --- a/.github/workflows/nightly.yaml +++ b/.github/workflows/nightly.yaml @@ -12,7 +12,7 @@ name: Nightly Build # Artifacts (under the running repo's owner): # ghcr.io//deer-flow-{backend,frontend,provisioner}:nightly # ghcr.io//deer-flow-{backend,frontend,provisioner}:nightly-YYYYMMDD -# oci://ghcr.io//deer-flow chart version -nightly.YYYYMMDD- +# oci://ghcr.io//charts/deer-flow chart version -nightly.YYYYMMDD- # # The nightly chart defaults image.tag=nightly and image.registry=ghcr.io/ # (patched in-workflow, never committed), so installing it pulls the matching @@ -230,5 +230,5 @@ jobs: helm package deploy/helm/deer-flow --destination ./packages for pkg in ./packages/*.tgz; do echo "--- pushing $pkg" - helm push "$pkg" oci://ghcr.io/${{ github.repository_owner }} + helm push "$pkg" oci://ghcr.io/${{ github.repository_owner }}/charts done diff --git a/RELEASING.md b/RELEASING.md index 0434d4bf9..fc968524e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -33,40 +33,40 @@ distinguishes it from a release. ## Helper scripts - `scripts/bump_version.sh ` — set all four fields at once, then - self-verify. Tolerates a leading `v` (e.g. `v2.2.0`). + self-verify. Tolerates a leading `v` (e.g. `v2.1.0`). ```bash - scripts/bump_version.sh 2.2.0 + scripts/bump_version.sh 2.1.0 ``` - `scripts/verify_versions.sh [version]` — check that all sources agree. With no argument it requires mutual equality; with an argument it requires every source to equal it. Exits non-zero on mismatch. Run it locally before tagging to catch drift early: ```bash - scripts/verify_versions.sh 2.2.0 + scripts/verify_versions.sh 2.1.0 ``` ## Release procedure 1. **Bump the version** across all sources: ```bash - scripts/bump_version.sh 2.2.0 + scripts/bump_version.sh 2.1.0 ``` 2. **Update `CHANGELOG.md`**: rename the `## [Unreleased]` section to - `## [2.2.0] — YYYY-MM-DD` (note the em dash `—`), and add a link reference + `## [2.1.0] — YYYY-MM-DD` (note the em dash `—`), and add a link reference at the bottom of the file: ``` - [2.2.0]: https://github.com/bytedance/deer-flow/releases/tag/v2.2.0 + [2.1.0]: https://github.com/bytedance/deer-flow/releases/tag/v2.1.0 ``` Start a fresh `## [Unreleased]` section above it for the next cycle. 3. **Commit** the version + changelog changes: ```bash git add -A - git commit -m "release: v2.2.0" + git commit -m "release: v2.1.0" ``` 4. **Tag and push**: ```bash - git tag v2.2.0 - git push origin v2.2.0 + git tag v2.1.0 + git push origin v2.1.0 ``` Pushing the tag triggers the publishing workflows (below). @@ -78,7 +78,7 @@ distinguishes it from a release. - `.github/workflows/chart.yaml` — packages the Helm chart and pushes it as an OCI artifact to `ghcr.io`. Users install with: ```bash - helm install deer-flow oci://ghcr.io//deer-flow --version 2.2.0 + helm install deer-flow oci://ghcr.io//charts/deer-flow --version 2.1.0 ``` ## Nightly builds @@ -96,16 +96,16 @@ Artifacts (under the running repo's owner, where `` is `YYYYMMDD`): (rolling, overwritten each run) and `:nightly-` (pinned to a day, but mutable within it - a same-day re-dispatch overwrites it). For a truly immutable pin, use `:sha-`. -- Chart: `oci://ghcr.io//deer-flow`, version `-nightly.-` - (e.g. `2.2.0-nightly.20260710-77a3652`). The short SHA makes each dispatch's +- Chart: `oci://ghcr.io//charts/deer-flow`, version `-nightly.-` + (e.g. `2.1.0-nightly.20260710-77a3652`). The short SHA makes each dispatch's chart version unique, so a same-day re-dispatch re-publishes cleanly (OCI chart versions are immutable and otherwise can't be overwritten). The packaged chart defaults `image.registry=ghcr.io/` and `image.tag=nightly`, so installing it pulls the matching nightly images with no values overrides: ```bash - helm install deer-flow oci://ghcr.io//deer-flow \ - --version 2.2.0-nightly.20260710-77a3652 + helm install deer-flow oci://ghcr.io//charts/deer-flow \ + --version 2.1.0-nightly.20260710-77a3652 ``` The chart version is patched in-workflow only - `Chart.yaml` and `values.yaml` @@ -122,20 +122,20 @@ When it fails, the job annotation names the offending file and suggests the fix: ``` -::error::frontend/package.json is '2.1.0' but expected '2.2.0'. -Tip: run scripts/bump_version.sh 2.2.0 to align all sources. +::error::frontend/package.json is '2.0.0' but expected '2.1.0'. +Tip: run scripts/bump_version.sh 2.1.0 to align all sources. ``` ## Pre-releases (RCs) -Pre-release tags like `v2.2.0-rc1` are valid `v*` tags and trigger the same +Pre-release tags like `v2.1.0-rc1` are valid `v*` tags and trigger the same workflows. The version sources must equal the full pre-release string -(`2.2.0-rc1`) — the gate compares exact strings. Use the same procedure with +(`2.1.0-rc1`) — the gate compares exact strings. Use the same procedure with the rc version: ```bash -scripts/bump_version.sh 2.2.0-rc1 -# update CHANGELOG, commit, tag v2.2.0-rc1, push +scripts/bump_version.sh 2.1.0-rc1 +# update CHANGELOG, commit, tag v2.1.0-rc1, push ``` ## Recovering from a failed gate @@ -146,10 +146,10 @@ If the gate failed because a source was forgotten: 2. Amend or add a follow-up commit. 3. Delete and re-create the tag, then push it: ```bash - git tag -d v2.2.0 - git tag v2.2.0 - git push origin :refs/tags/v2.2.0 - git push origin v2.2.0 + git tag -d v2.1.0 + git tag v2.1.0 + git push origin :refs/tags/v2.1.0 + git push origin v2.1.0 ``` Re-pushing the tag re-triggers the workflows. Because the gate blocks **all** @@ -161,3 +161,8 @@ is safe — no images or chart were pushed to overwrite. Optionally draft a **GitHub Release** from the tag, pasting the corresponding `CHANGELOG.md` section as the release notes. The changelog link references point at these release URLs. + +For the 2.1.0 chart release (the first chart release), pre-`charts/` nightly +builds remain at the legacy bare `ghcr.io//deer-flow` package. That +package receives no new versions after 2.1.0; delete it or revoke its +visibility once nothing still pulls from it. diff --git a/deploy/helm/deer-flow/README.md b/deploy/helm/deer-flow/README.md index 92a3f283d..5be387125 100644 --- a/deploy/helm/deer-flow/README.md +++ b/deploy/helm/deer-flow/README.md @@ -11,7 +11,7 @@ Kubernetes resources. No existing repo files are modified. ## Prerequisites - A Kubernetes cluster (Docker Desktop K8s, OrbStack, kind, k3d, or a real cluster). -- `kubectl` + `helm` 3 installed. +- `kubectl` + `helm` 3.8+ installed (OCI registry support stabilized in 3.8; earlier 3.x needs `HELM_EXPERIMENTAL_OCI=1`). - The three DeerFlow images — either the published ones (see "Install the published chart" below) or built locally (see step 1). - An Ingress controller (e.g. ingress-nginx) if you enable `ingress`. @@ -23,7 +23,7 @@ The chart and all three images are published to GHCR on every `v*` release tag and install directly: ```bash -helm install deer-flow oci://ghcr.io//deer-flow \ +helm install deer-flow oci://ghcr.io//charts/deer-flow \ --version \ -n deer-flow --create-namespace \ -f my-values.yaml @@ -31,7 +31,14 @@ helm install deer-flow oci://ghcr.io//deer-flow \ where `` is the GitHub owner the chart is published from and `` matches the release tag without the leading `v` (tag `v0.1.0` → `--version -0.1.0`). Point the chart at the published images: +0.1.0`). + +> **Note:** the helm chart is new in 2.1.0 - no chart was published before it. +> It publishes to `oci://ghcr.io//charts/deer-flow` (the `charts/` prefix +> keeps it distinct from the `deer-flow-{backend,frontend,provisioner}` image +> packages). + +Point the chart at the published images: ```yaml image: @@ -58,11 +65,25 @@ Skip this section if you're using the published chart above. To build the images yourself from the existing Dockerfiles: ```bash -REGISTRY=ghcr.io/yourorg TAG=latest ./deploy/helm/deer-flow/scripts/build-and-push.sh +REGISTRY=ghcr.io/yourorg +TAG=latest + +# backend - build with the `postgres` extra so multi-replica deploys can use +# shared Postgres (matches the published image) +docker build -t $REGISTRY/deer-flow-backend:$TAG --build-arg UV_EXTRAS=postgres -f backend/Dockerfile . +# frontend +docker build -t $REGISTRY/deer-flow-frontend:$TAG -f frontend/Dockerfile . +# provisioner +docker build -t $REGISTRY/deer-flow-provisioner:$TAG -f docker/provisioner/Dockerfile docker/provisioner + +docker push $REGISTRY/deer-flow-backend:$TAG +docker push $REGISTRY/deer-flow-frontend:$TAG +docker push $REGISTRY/deer-flow-provisioner:$TAG ``` -This produces `$REGISTRY/deer-flow-backend`, `$REGISTRY/deer-flow-frontend`, -`$REGISTRY/deer-flow-provisioner`. The chart's image-name defaults match these. +These names match the chart's `gatewayImage` / `frontendImage` / +`provisionerImage` defaults, so only `image.registry` and `image.tag` need to +point at them. If your registry needs auth, create a pull secret: diff --git a/deploy/helm/deer-flow/templates/NOTES.txt b/deploy/helm/deer-flow/templates/NOTES.txt index 2453c67ab..236a75e0b 100644 --- a/deploy/helm/deer-flow/templates/NOTES.txt +++ b/deploy/helm/deer-flow/templates/NOTES.txt @@ -6,7 +6,7 @@ DeerFlow has been deployed. ⚠️ WARNING: `image.registry` is empty. The gateway/frontend/provisioner images won't resolve. Set `image.registry` in your values and build+push the - three images (see deploy/helm/deer-flow/scripts/build-and-push.sh). + three images (see the chart README's "Build & push images" section). {{- end }} Get the status: