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 required 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	What it verifies
lint	ci.yaml	scripts/check-versions.sh (version pins and markdown tokens), ruff on the gateway, shellcheck on shell scripts, yamllint/actionlint when available.
python	ci.yaml	Gateway unit tests (pytest).
manifests	ci.yaml	scripts/check-examples.sh, scripts/check-manifests.py and a server-side dry-run of every example manifest against the agent-sandbox CRDs.
gateway-image	ci.yaml	Builds the gateway image and smoke-tests /healthz without a cluster.
pr-title	pr-title.yaml	Conventional Commit PR title.
CodeQL	codeql.yml	Static analysis for Python and GitHub Actions.
dependency-review	ci.yaml	Dependency changes introduced by the PR (job dependency-review; runs on pull requests only).

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

All release tags match dsh-* and are protected:

• 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 checks lint, python, manifests, gateway-image, pr-title, CodeQL, dependency-review; 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.