deepseek-kubernetes-sandbox/docs/gitflow.md

Gitflow: branches, pull requests and CI

This repository uses trunk-based development with release branches. main is always releasable; feature work happens on short-lived branches; releases are cut from main onto a release branch and tagged with an immutable release identity. See versioning for what the tags mean.

Branches

Branch	Branched from	Merged into	Purpose
main	—	—	The integration trunk. Protected, linear history, always releasable.
feat/<slug>	main	main (squash)	New capability or example.
fix/<slug>	main	main (squash)	Bug fix.
docs/<slug>	main	main (squash)	Documentation only.
refactor/<slug>, chore/<slug>, test/<slug>	main	main (squash)	Non-behavioral rework, maintenance, tests.
release/<identity>	main at the release commit	—	Release stabilization and tagging. Only release-blocking fixes land here.
hotfix/<slug>	The release branch (or the tagged commit)	main and the release branch	Urgent production fix.

Keep branches short-lived. Rebase on main rather than merging main into the branch; the PR is squash-merged, so individual branch commits are never part of main history.

Pull requests

1. One scoped change per PR. Do not mix a version bump with unrelated work, and update the docs the change touches in the same PR.
2. Conventional PR title. The title becomes the squash commit message, so it is linted by the pr-title check: feat(scope): ..., fix(scope): ..., docs(scope): ..., build: ..., ci: ..., refactor: ..., test: ..., chore: .... Breaking changes use feat(scope)!: ... or a BREAKING CHANGE: footer.
3. CI must be green. All applicable checks below must pass before merge.
4. Squash merge only. main stays linear and protected; merged PRs are one commit each.
5. No direct pushes to main or to a release branch. Both are protected.
6. Review for behavior changes. Infrastructure, workflow, release and gateway-contract changes need a maintainer review; trivial docs changes still need the checks.

Required checks

Check	Workflow / job	Required on every PR?	What it verifies
lint	ci.yaml	yes	scripts/check-versions.sh (version pins and markdown tokens), scripts/check-examples.sh (example layout and numbered manifests), shellcheck, actionlint, yamllint, hadolint and documentation links.
python	ci-python.yaml	no (path-filtered)	Gateway ruff check/format and unit tests (pytest with coverage). Runs only when the gateway or this workflow changes.
manifests	ci-manifests.yaml	no (path-filtered)	scripts/check-manifests.py (manifest shape) and a server-side dry-run of every example manifest against the agent-sandbox CRDs. Runs when manifest files, scripts/check-manifests.py or versions.env change.
pr-title	pr-title.yaml	yes	Conventional Commit PR title.
Analyze (python), Analyze (actions)	codeql.yml	yes (both jobs)	CodeQL static analysis for Python and GitHub Actions.
dependency-review	ci.yaml	yes	Dependency changes introduced by the PR (job dependency-review; runs on pull requests only).

python, manifests and build-amd64 use native on.pull_request.paths filtering, so PRs that do not touch the gateway, the manifests or the image definition skip them. The gateway image is built and published by build-gateway.yaml on merge; /healthz is covered by the gateway unit tests and the Dockerfile is linted by lint (hadolint).

ci-image.yaml (build-amd64) is the PR-side check for the main image: when Dockerfile, .dockerignore or versions.env change it builds linux/amd64 with the pins from versions.env — no registry login, no push — and smoke-tests the result (--version, non-root UID, /workspace + DSH_HOME, the bubblewrap runner, the version label, and /favicon.svg served from a running container). The published multi-arch build still happens only in build-main.yaml on merge.

Because a skipped path-filtered check is not a passing check, require only the always-on set: lint, pr-title, both CodeQL Analyze jobs and dependency-review. Keep python, manifests and build-amd64 as on-demand checks that skip when unrelated to the change.

The image build workflows (_build-image.yaml, build-main.yaml, build-gateway.yaml) and e2e-kind.yaml are not required on every PR: the image builds run where they are needed, and the kind end-to-end suite is reserved for release validation and manual dispatch because it is slow.

Releases

Releases are cut from main:

1. Confirm main is green and make check, make test, make lint pass.
2. Bump versions.env if the DSH ref changed, using make set-version; otherwise keep the same DSH_VERSION and bump RELEASE_REVISION.
3. Create release/<identity> from the release commit.
4. Run make release-dry-run and review the generated notes.
5. Create and push the annotated dsh-* release tag. The release.yaml workflow validates that the tag matches versions.env, builds and pushes the multi-arch images (version + latest), creates the GitHub Release from the git-cliff notes, and opens a chore(changelog) PR that refreshes CHANGELOG.md on main.
6. Merge the changelog PR and any release-branch-only fixes back to main.

Full procedure: versioning.

Hotfixes

A released tag is never moved or re-tagged — tags and image identities are immutable. To fix a broken release:

1. Branch hotfix/<slug> from the release tag (or its release branch).
2. Make the minimal fix, add a test, open a PR; the same required checks apply.
3. Publish a new identity with a higher RELEASE_REVISION (-r(N+1)). Do not reuse or delete the broken tag.
4. Merge the fix back into main (or cherry-pick it) so the trunk is fixed too.

Rollback is also a re-release, never a retag: see versioning.

Tag protection

Release tags follow dsh-* and are protected (the pre-scheme v0.0.1 tag is historical and unmaintained):

• only maintainers (the release workflow) may create them;
• they cannot be deleted or force-updated;
• they are annotated and point at the release commit on a release branch.

Image tags derive from the same identity and are equally immutable; the mutable latest and main image channels always point at a release or a trunk build respectively.

One-time GitHub settings checklist

Configure these on the repository before relying on the workflow:

• Branches → main: require a pull request; require the always-on checks lint, pr-title, both CodeQL Analyze jobs and dependency-review (python, manifests and build-amd64 are path-filtered and must not be required); require branches to be up to date; require conversation resolution; restrict direct pushes; allow only squash merges and enable "Automatically delete head branches".
• Branches → release/*: same protections, plus allow the release workflow to push tags.
• Tags → dsh-*: restrict creation/update/deletion to maintainers; a tag push triggers the release workflow.
• Actions → General: allow GitHub Actions; set workflow permissions to read-only by default; allow GITHUB_TOKEN to create pull requests only where required.
• Actions → Runners: make the arm64 runners (ubuntu-24.04-arm) available to the public/private repository as appropriate.
• Packages: grant the release workflow packages: write (workflow permissions do this) and protect the ghcr.io/sredevopsorg/deepseek-kubernetes-sandbox packages from deletion.
• Security: enable CodeQL default setup or keep the advanced codeql.yml workflow (not both), enable Dependabot alerts and dependency review.
• Secrets/Variables: none are needed for image publishing; the workflows use GITHUB_TOKEN.