Skip to content

✨ Reference repos: per-hive write identity, bot / bot only / owner (backend) (#18516) - #18521

Merged
kubestellar-prow[bot] merged 2 commits into
v5from
feat/remote-write-identity
Nov 16, 2026
Merged

kubestellar-prow[bot] merged 2 commits into
v5from
feat/remote-write-identity

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Part 1 of #18516 (follow-up to #18196). This PR covers the backend: identity resolution, the App mint, the proxy credential for each policy, and the kick text. The Settings control, the API and the docs come in a second PR.

What it does

The new key project.remote_write_identity sets whose name appears on the issues, PRs and comments a hive posts on a granted write-tier reference repo:

Setting App installed on the repo (by its owner) App not installed
bot (default; a missing key reads as this) hivecommons-hive[bot] owner's connected account, otherwise read-only
bot_only hivecommons-hive[bot] read-only; the owner token is never read
owner owner's connected account owner's connected account (today's behaviour)
  • The grant comes first. Only entries already at the write tier get a token source: hand-written entries, or entries derived from an accepted request issue (📝 RFC: derive write-tier reference repos from an accepted assessment request issue (no hub, no token on the spoke) #18139). An App installation shared by many hives, such as the one on the hivecommons org, is not a grant by itself. A test covers this: the App is installed on all of hivecommons, and the only token minted is for the one granted repo.
  • App detection only. The hive calls GET /repos/{owner}/{repo}/installation with the App JWT, so an install limited to selected repos is respected. Results are cached like the org discovery. Nothing asks a project to install the App. The read-only notice names no cure under bot_only.
  • Mint scope. The token is minted on the installation that covers that repo. It is scoped to that one repo with metadata:read, issues:write (issues tier), and contents:write plus pull_requests:write (prs tier). It is never minted on the hive's own installation. It is cached until shortly before expiry, and the installation is looked up again on each mint, so a removed App stops yielding tokens.
  • Transient lookup failures leave the entry read-only for that pass (credential_state: unresolved, with no request-issue notice). The hive does not silently switch to the owner's name.
  • write_token_file still wins on hand-written entries.
  • Proxy restrictions are unchanged whatever the identity: no labels, assignees, reviews, closing other people's items, merges or default-branch pushes. One small change: a [bot] login never names a fork, so bot PR branches are pushed to the reference repo itself, under the same default-branch guard. An App cannot own a fork.
  • Kick text. The kick now gives the bot flow ("do NOT fork, push the topic branch to the repo, --head <branch>") next to the owner's fork flow.
  • Own-item follow-up. The poller keeps to owner-identity repos, because it reads under the owner token and lists creator=<owner>. Follow-up on bot-authored items will be tracked separately.

How existing hives behave after upgrade

No hive has the key yet, so every hive reads as bot.

  • Repo where the App is not installed: the owner's account if connected, otherwise read-only. Same as today.
  • Granted repo where the repo's owner installed the App: the hive now posts as hivecommons-hive[bot] instead of the owner. This is the intended change. Example: the hivecommons repos derived from [Assessment request]: Hive Commons (pilot of the AI-assisted assessment workflow) cncf/techdocs#395 now post as the bot without the owner connecting an account.
  • Hand-written write entry with no owner connected and no token file: today this refuses boot. It now boots when the App covers that repo.

Owners who want today's behaviour can set owner. That control lands in part 2.

Tests

  • pkg/github/reference_repo_identity_test.go: the full matrix of setting (""/bot/bot_only/owner) × App installed × owner connected. Also: bot_only never resolves to the owner, read-only entries get nothing under any setting, a transient failure never switches identity, the token file wins, the token source is cached and per repo, and an httptest check of the real mint (repository-level installation lookup, repositories: ["docs"], the exact permission set, never the hive's own installation).
  • cmd/hive/reference_repos_identity_test.go: the pilot case, the no-grant-no-token invariant, bot_only never reading the owner token, the per-repo credential in a mixed set, and transient lookups staying read-only.
  • crux/proxy/reference_repos_identity_test.go: the proxy injects each repo's own credential on each call, read-only repos get nothing, a bot push goes to the repo under the default-branch guard, management is refused under both identities, and a bot login never names a fork.
  • Config validation and kick text tests.

The settings-parity allowlist gets project.remote_write_identity until part 2 adds the control.

Refs #18516

🤖 Generated with Claude Code

…8516)

project.remote_write_identity picks whose name a granted write-tier
reference repo's issues, PRs and comments carry:

- bot (default; a missing key reads as bot): the hive's GitHub App bot on a
  repo whose owner installed the App themselves (GET /repos/{o}/{r}/installation
  with the App JWT, cached like org discovery), else the owner's connected
  account, else read-only.
- bot_only: the App bot where installed, read-only elsewhere; the owner token
  is never read.
- owner: the owner's connected account everywhere (the #18197 behaviour).

The setting never widens a grant: only entries already at the write tier
(hand-written or derived from an accepted request issue, #18139) get a token
source, so an App installation shared by many hives is not a grant by itself.
The bot token is minted on the installation covering that one repo, scoped
to that repo and to the tier's permissions (metadata read; issues write;
contents and pull_requests write for prs), cached until near expiry, and
injected only by the existing reference-repo proxy path. A transient lookup
failure serves the entry read-only for the pass (state unresolved) instead of
silently switching identity. write_token_file still wins on hand-written
entries. Every proxy refusal is unchanged; a bot login never names a fork,
so bot PR branches go to the repo itself under the default-branch guard.

The kick names the bot flow (no fork) beside the owner fork flow, the
request-issue read-only notice names no cure under bot_only, and the
own-item follow-up poller keeps to owner-identity repos.

Refs #18516

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#18536 ✨ feature: choose remote repository write identity same files changelog.d/added-18516-remote-write-identity.md
src/cmd/hive/reference_repos.go
src/cmd/hive/reference_repos_identity_test.go
src/cmd/hive/remote_items.go
src/crux/proxy/reference_repos.go
src/pkg/config/config.go
src/pkg/config/reference_repos.go
src/pkg/config/validate.go
src/pkg/github/reference_repo_request.go
src/pkg/github/reference_repo_token.go
src/pkg/scheduler/kickmessage.go
#18519 ✨ Sandbox kicks get hive's relays (hive-review) on PATH from the hive image same files src/pkg/dashboard/settings_parity_allowlist.txt
#18507 ✨ governor: release-feed watcher kicks agents when a tracked upstream dependency releases same files src/pkg/config/config.go
src/pkg/config/validate.go
src/pkg/dashboard/settings_parity_allowlist.txt
#18542 🐛 hive never applies hold itself: gates use ready-for-review / decision-needed same files src/pkg/config/config.go
src/pkg/dashboard/settings_parity_allowlist.txt
#18540 🐛 inference: refresh rotated gateway keys and refuse ignored api_key_file paths same files src/pkg/config/config.go
src/pkg/config/validate.go
#18505 ✨ Discover agents declared in a managed repo's .hive/agents/ behind owner approval same files src/pkg/dashboard/settings_parity_allowlist.txt

…sient App lookup (#18516)

The resolved list replaces the config in memory and the editor saves from
it, so clearing Write on a blip would persist as an edit. The entry keeps
Write, is marked unresolved, and gets a read-only proxy policy for the
pass; the kick says it is read-only this pass.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@github-actions

Copy link
Copy Markdown
Contributor

Mutation testing

⏱️ The 900s mutation budget ran out, so 1 package(s) were not fully mutated and the results below do not cover them:

  • pkg/scheduler: skipped (not started)

❌ gremlins did not produce a report for 1 package(s), so no verdict can be derived from this run (see the job log):

  • pkg/github: gremlins exited 137

2 mutant(s) in changed files are not reached by any test (NOT COVERED). A maintainer may apply the mutation/acknowledged label to accept this.

File Line Mutation
src/cmd/hive/reference_repos.go 214 CONDITIONALS_NEGATION
src/cmd/hive/reference_repos.go 220 CONDITIONALS_NEGATION

ℹ️ 4 mutant(s) on added lines were SKIPPED because gremlins v0.6.0 only honours the first lines added lines of each default-context hunk, so non-contiguous edits in one hunk are partly missed. This does not affect the verdict.

File Line Mutation
src/cmd/hive/reference_repos.go 116 CONDITIONALS_NEGATION
src/cmd/hive/reference_repos.go 123 CONDITIONALS_NEGATION
src/cmd/hive/remote_items.go 78 CONDITIONALS_NEGATION
src/crux/proxy/reference_repos.go 82 CONDITIONALS_NEGATION

Verdict: error (#17349).

@clubanderson

Copy link
Copy Markdown
Member Author

@nate-double-u FYI, backend for the bot / bot only / owner setting (#18516). Once this and the Settings UI land, pick "Hive bot only" under Settings, Repos, Reference repos.

@clubanderson clubanderson added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Nov 16, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 16, 2026
@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 16, 2026
@kubestellar-prow
kubestellar-prow Bot merged commit 0f11d4c into v5 Nov 16, 2026
95 of 97 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/remote-write-identity branch November 16, 2026 22:53

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style review (head 2acf6cb) — no in-scope blocker; three advisory notes.

  1. Bot detection by string suffix in the proxy (src/crux/proxy/reference_repos.go, forkSlug): strings.HasSuffix(r.Login, "[bot]") re-derives "this is the App identity" from the login text, while the PR already models that as config.ReferenceIdentityBot (src/pkg/config/remote_write_identity.go) and sets it in cmd/hive/reference_repos.go. Two sources of truth for one fact. Consider an explicit field on proxy.ReferenceRepoPolicy (e.g. NoFork bool/Identity) set where pol.Token is chosen, so the proxy does not parse logins.

  2. Constructing a throwaway ProjectConfig to normalise a string (src/pkg/github/reference_repo_identity.go, mode := (config.ProjectConfig{RemoteWriteIdentity: setting}).EffectiveRemoteWriteIdentity()). The effective-value logic lives on ProjectConfig only because the field does. A package-level config.EffectiveRemoteWriteIdentity(v string) string that the method delegates to would read more directly at this call site.

  3. Allowlist placement (src/pkg/dashboard/settings_parity_allowlist.txt:624): project.remote_write_identity is inserted in the middle of the project.workflow_bindings[] group, so its neighbours do not relate to it. Move it next to the other project.* reference-repo/settings entries, or keep it, but it breaks the grouping.

— hive: agent=adjudicator-4 backend=claude model=claude-sonnet-5-5 claude=2.1.325

@hivecommons-hive

hivecommons-hive Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from adjudicator-5 (folded here because this head already carries its hive review):

Docs-currency review (head 2acf6cb) — changes requested; the PR defers docs to part 2, but it flips the default behaviour now, so three operator docs become false on merge.

  1. Docs say "never the hive's App", which this PR reverses. The default bot now mints a token on the repo owner's App installation (pkg/github/reference_repo_identity.go, reference_repos.go).

    • src/docs/github-write-surface.md:267: "...or, on a hand-written entry, a write_token_file; never as the hive's App."
    • src/docs/agent-configuration.md:1191: "never the hive's own installation token and never an installation of the hive's GitHub App on the target org (✨ Remote repos: write as the hive owner, not the App (two-lane issue/PR management) #18196)... The credential is the hive owner's own GitHub account." Line 1189 (fork-and-PR only), 1205, 1215 and 1223 describe only the owner/fork flow.
    • src/docs/operator-reference/README.md, the project.reference_repos[].write row: it describes App-installed-on-target-org minting but not the new key. There is also no row for project.remote_write_identity. The PR adds the key to settings_parity_allowlist.txt and config.go, so it is an operator-visible setting with no entry in the operator reference.

    A hive owner reading these after upgrade gets the wrong answer to "whose name appears on my writes?". The PR body's own upgrade note says existing hives silently switch to the bot.

    Requested fix: a minimal doc patch in this PR. Part 2 can still own the Settings control and the full prose. Suggested replacement for github-write-surface.md:267:

or, on a hand-written entry, a `write_token_file` — or, where the repo's owner installed the hive's GitHub App on that repo, as the App bot (`project.remote_write_identity`: `bot` default, `bot_only`, `owner`; hivecommons/hive#18516).

Add one project.remote_write_identity row to the operator reference (values, default bot, the fallback table from the PR body). Amend the "never ... App" sentence at agent-configuration.md:1191 the same way.

  1. Changelog wording (low). changelog.d/added-18516-remote-write-identity.md is accurate. It could add that existing hives switch to the bot on repos where the App is installed, since that is the user-visible upgrade change. Optional.

Limits: I did not check whether a doc-parity test enforces operator-reference rows for new config keys.

Review findings from adjudicator-2 (folded here because this head already carries its hive review):

Security review (head 2acf6cb) — one in-scope blocker.

1. Bot identity widens the push gate from "own fork" to "any non-default ref on the upstream repo" (medium-high)

src/crux/proxy/reference_repos.go:82 — the PR makes forkSlug() return "" for [bot] logins, so a bot-identity policy has no fork and pushes go straight to Repo (stated in the comment above it). Before this PR a prs-tier agent could only push to the owner's own fork, a repo it fully owns. The only guard on upstream pushes is the default-branch check at reference_repos.go:285-291, which rejects refs/heads/<default> and nothing else. The App token is minted with contents:write on the target repo (reference_repo_identity.go, referenceRepoPermissions). peekReceivePackRefs returns only the ref name, so the old/new SHAs are discarded.

Consequence: a prompt-injected or misbehaving agent can use the bot token to:

  • force-push over, or delete (new sha 0000…), any other non-default branch (release/*, a maintainer's or contributor's branch), unless the upstream repo has branch protection on it;
  • create or delete refs/tags/*.

That breaks the documented contract ("push a topic branch and open a PR") on a third party's repo. Bot is the default setting, so this is the common path. The PR's own tests don't cover it.

Requested fix: for a bot-identity policy, restrict pushes to topic branches that are new and namespaced, and refuse deletes and tags. peekReceivePackRefs needs to also return the old sha. Sketch:

 		for _, ref := range refs {
 			if ref == "refs/heads/"+def {
 				return referenceRepoRefusal(pol, "pushing to its default branch ("+def+") is never allowed — push a topic branch and open a PR"), true
 			}
+			if strings.HasSuffix(pol.Login, "[bot]") && !strings.HasPrefix(ref, "refs/heads/hive/") {
+				return referenceRepoRefusal(pol, "the bot identity may only create topic branches named hive/<topic>"), true
+			}
 		}

and in peekReceivePackRefs, also require old == 0000… and new != 0000… for bot policies (create-only, no update or delete). Add a proxy test with a refs/heads/release/1.0 update, a delete and a tag push.

Minor (info, no verdict impact)

  • Own-item check (reference_repos.go:271) compares against Login. The App's [bot] login is shared by every hive using that App, so a bot policy can also comment on items another hive's bot opened. Consider also keying on a hive marker.

Not verified: the real AppAuth.mintInstallationTokenWithOptions body was outside the diff and I did not read it. The Repositories/Permissions options are passed as the diff shows.

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review (head 2acf6cb)

  1. High: bot pushes to upstream are guarded only on the default branch. src/crux/proxy/reference_repos.go:81-83 makes forkSlug empty for [bot] logins, so the bot pushes topic branches into the upstream repo with contents:write (reference_repo_identity.go referenceRepoPermissions). The push gate (reference_repos.go:275-292) rejects only refs/heads/<default>. The bot can therefore overwrite or delete release branches and other people's branches. Previously pushes were confined to the owner's fork. Please restrict bot-login policies to a hive-owned branch prefix and refuse deletions in the referencePush case, with a test.

  2. Low: bot_only + hand-written entry returns ErrReferenceRepoNoCredential (reference_repo_identity.go:651), while the PR table says "read-only". Confirm intended and that reload tolerates it.

  3. Low: remote_items.go:78 skips bot entries from polling; since bot is the default, replies on the bot's items are no longer picked up where the App is installed.

Karibhou pushed a commit to Karibhou/hive that referenced this pull request Nov 17, 2026
- Build on the merged hivecommons#18521 backend and expose its identity and provenance in Settings.
- Serialize setting changes with reference-repo re-resolution.

Co-authored-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: hivecommons-hive[bot] <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Karibhou added a commit to Karibhou/hive that referenced this pull request Nov 17, 2026
- Build on the merged hivecommons#18521 backend and expose identity and provenance in Settings.
- Serialize setting changes with reference-repo re-resolution.

Co-authored-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant