[swkeever]

Merge after hosting#2184 is in production. The connection's production_branch_follows_default field and --reset both need #2184's server. Against a server without it, the field reads as false, so every branch would show as pinned. There's deliberately no fallback for that.

Draft: stacked on #341. The spec comes from Kong/volcano-hosting#2184, which is still open; it will be copied again verbatim once that PR is on main.

What

volcano git production-branch <branch> and volcano git production-branch --reset change only the branch a push has to land on to deploy. The repository binding is left as it is.

$ volcano git production-branch release
✓ Production branch set to release
  Project: storefront
  Repository: octo/storefront
  Production branch: release (pinned)
Nothing was redeployed. release stays the production branch if the repository's default branch changes.

A push to release deploys: functions

$ volcano git production-branch --reset
✓ Production branch now follows the repository's default branch (main).
...

• Naming a branch pins it. A later rename or change of the repository's default branch on GitHub leaves it alone. The branch doesn't have to exist yet.
• --reset sends {"production_branch": ""}. The server reads the default branch from GitHub and returns it in the connection with production_branch_follows_default: true.
• Project tokens work, as they do for root-directory, so CI or an agent can run the command.
• After the change, the command says what a push to the production branch deploys, including when auto-deploy is off. If the deploy settings can't be read afterwards, the command still succeeds and says so.
• Server refusals are shown as the server gave them:
  • 400: an invalid branch name, or --reset on a repository with no default branch yet.
  • 409: the owner's GitHub connection needs reconnecting or lost access, or the source is being exported.
• A 404 goes through the not-connected check root-directory already uses:
  • A missing project is reported as missing.
  • A project with nothing connected is told to connect a repository.
  • Local mode says the GitHub integration isn't configured.
  • guideBindingEdit now holds that check for both commands.

Keeping a pinned branch

Hosting#2184 adds production_branch_follows_default to ProjectGitConnection. Without it, re-running volcano git connect would silently drop a pin. This PR uses the field as follows:

• connect treats a branch other than GitHub's default as stale only when the branch follows the default. A pinned branch, including one that equals today's default, reports "already connected" and writes nothing.
• A rebind of the same repository sends a pinned branch back. This covers a reinstalled App and a renamed repository. Leaving production_branch out would make the project follow the default again.
  • A different repository starts from its own default, as before.
• connect --root-directory on a pinned project uses the root-directory route, which leaves the branch alone.
• The binding check compares the flag. If someone pins or unpins between the read and the rebind, the command stops instead of undoing their change.
• status and every git command show the branch with its state, for example Production branch: release (pinned) or Production branch: main (follows the default).
• production-branch reads the state from the response, not from whether --reset was passed.

Spec

Every hunk of hosting#2184's api/openapi.bundled.yaml at 9cc0518e is applied unchanged:

• the production-branch route accepts an empty branch, with the new 400 and 409 cases;
• the required production_branch_follows_default on ProjectGitConnection;
• the descriptions for the connection read and the connect PUT.

The client is regenerated. I'll copy the spec again verbatim once #2184 is on main.

Tests

• internal/cmd/git/production_branch_test.go covers:
  • pinning a branch and resetting it;
  • auto-deploy being off, and deploy settings that can't be read;
  • a project access token;
  • argument refusals;
  • the server's 400, 409 and 403 refusals;
  • nothing connected, a missing project, and local mode.
• connect_test.go covers:
  • a pinned branch (release, and main equal to the default) left alone;
  • a same-repository rebind sending the pin back, or nothing when the branch follows the default;
  • a different repository not carrying the pin;
  • --root-directory on a pinned project;
  • a pin changed during the command being refused.
• status_test.go covers both states.
• The test fake in helpers_test.go serves the production-branch route and models the flag the way the platform does.
• tests/e2e/localmode/git_test.go now runs volcano git production-branch release against the local stack as well as root-directory, in CI's localmode-e2e job.
• The cloud round trip goes in a hosting E2E PR under the CLI lane, like hosting#2161.

Docs

docs/git.md gains:

• a "Changing the production branch" section;
• an operations row;
• the project-token note;
• a local-mode note.

It also stops saying that only a push to the default branch deploys.

🤖 Generated with Claude Code