From 1d55afd8183c5b833259180e99b60cda47cd4744 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 4 Nov 2026 20:04:18 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20docs:=20app=5Fsigned=5Fcommits?= =?UTF-8?q?=20is=20a=20Settings=20toggle;=20add=20operator-reference=20row?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit running-at-level-6.md G8 called github.app_signed_commits YAML-only, but the dashboard has had the switch under Settings → Forge App since the toggle landed, and operator-reference/README.md had no row for the key at all. Add the row (default off, App-only, what it rewrites, fallbacks, Settings location, link to github-app-setup.md) and name the dashboard location in github-app-setup.md next to the YAML snippet. Signed-off-by: Andrew Anderson --- changelog.d/changed-app-signed-commits-docs.md | 1 + src/docs/github-app-setup.md | 2 ++ src/docs/operator-reference/README.md | 1 + src/docs/running-at-level-6.md | 2 +- 4 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelog.d/changed-app-signed-commits-docs.md diff --git a/changelog.d/changed-app-signed-commits-docs.md b/changelog.d/changed-app-signed-commits-docs.md new file mode 100644 index 0000000000..abc5a7a904 --- /dev/null +++ b/changelog.d/changed-app-signed-commits-docs.md @@ -0,0 +1 @@ +- Docs: `github.app_signed_commits` now has an operator-reference row (default off, App-only, what it rewrites, fallbacks, Settings location) and the level-6 checklist and `github-app-setup.md` point at its dashboard switch (Settings → Forge App → "Re-author agent PRs as GitHub-signed commits") instead of calling it YAML-only. diff --git a/src/docs/github-app-setup.md b/src/docs/github-app-setup.md index 81db0abb0c..32fc466ff8 100644 --- a/src/docs/github-app-setup.md +++ b/src/docs/github-app-setup.md @@ -209,6 +209,8 @@ github: app_signed_commits: true # opt-in; needs an installed App ``` +In the dashboard the same switch is **Settings → Forge App → Re-author agent PRs as GitHub-signed commits** (Owner role required to save). + With it on, the PR-request watcher (the choke point every `hive-open-pr` request passes through) re-authors the head branch before it opens the PR: it reads the `base...head` diff, builds one commit through the mutation with the App installation token — same tree, the agents' original commit messages and DCO trailers as the message — force-updates the branch to it, and then opens the PR. The PR arrives with a single commit, signed by GitHub, authored by `[bot]`, that a `required_signatures` rule accepts. **DCO.** The mutation takes no author: GitHub stamps its own bot account on the commit (`[bot] `). That is fine for the DCO checks - probot-dco exempts a commit whose GitHub author resolves to a Bot account, and Prow's `dco` plugin only requires a `Signed-off-by` line to be present. The `Signed-off-by` trailers copied from the agents' commits are what the hive controls, and they are re-addressed to the bracket-free form the pane identity uses since #6276: a `[bot]@users.noreply.github.com` sign-off (with or without GitHub's numeric prefix) becomes `@hive.kubestellar.io` (`HIVE_GIT_BOT_EMAIL_DOMAIN`), because probot-dco rejects the bracketed local-part as "not a valid email address" wherever it does validate it (#6251). Every other sign-off address, a human's or the legacy `hive-bot@kubestellar.io`, is copied unchanged. diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index 2757cd42a3..cd7e9ed183 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -241,6 +241,7 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through | `github.pr_detail_ttl_s` | `1800` seconds. `HIVE_GITHUB_PR_DETAIL_TTL` overrides for tests/experiments. | Reuses `GET /pulls/{number}` detail responses while the cheap PR list still reports the same `head.sha` and `updated_at`, and GitHub has resolved `mergeable_state`. | | `github.graphql_pr_batch` | `true` | Uses one paginated GraphQL query per repository scan to populate the PR detail cache and CI rollup cache, replacing most per-PR `GET /pulls/{number}` and `check-runs` reads. Set `false` to return to the REST-only scan path. | | `github.graphql_pr_batch_page_size` | `50` | Page size for the GraphQL `pullRequests(first:)` batch. Values above GitHub's `100` maximum are rejected. | +| `github.app_signed_commits` | Unset (off). App-authenticated hives only; PAT-authenticated hives ignore it. Settings → Forge App → **Re-author agent PRs as GitHub-signed commits** (Owner role). | Opt-in for repositories whose ruleset requires signed commits (`required_signatures`). Agents commit with plain `git` in their pane and cannot sign, so without it every agent PR is unmergeable there however many approvals it has. With it on, the PR-request watcher re-authors the head branch before the PR opens as one commit created through the GraphQL `createCommitOnBranch` mutation with the App installation token — same tree, the agents' messages and DCO trailers as the message — which GitHub signs and shows as **Verified**, authored by `[bot]`. A reconcile pass (at most once a minute) re-signs the hive's own unsigned follow-up pushes on open App-authored PRs the same way. Falls back to the plain unsigned push (PR still opens; `signed_skipped` in the request's `.result.json` and a WARN in the hive log) for changes the mutation cannot express (executable bits, symlinks, submodule pointers), more than 20 MiB of content or 300 files, a head that moved mid-rewrite, or a head that already has an open PR. A person's commit or a merge commit in the range stops the reconcile with one `hive:signed-commits-blocked` comment. See [github-app-setup.md](../github-app-setup.md#signed-commits-on-agent-prs-app_signed_commits). | | `governor.logging.kick_log_source` | `scrollback`. Also `transcript` or `auto`; unknown values mean `scrollback`. `HIVE_KICK_LOG_SOURCE` (when set to a valid value) wins over this key. | What per-kick logs (archives and the live full log) are built from: the tmux scrollback, the backend CLI's own transcript (Copilot CLI, Claude Code), or the transcript when a reader exists else the scrollback. Editable under **Settings → Logging → Kick log source**; applies to the next kick without a restart, and each log's header `source:` line (and the kick history page) shows which was used. See [agent-logging.md](../agent-logging.md#per-kick-log-history). | | `governor.labels.automerge` | Defaults to `lgtm`. | Label applied when a merger/owner queues a PR for Hive auto-merge-on-green. With Prow's commit binding (prow-github-actions v3), Hive binds `lgtm` by also setting the `prow/lgtm` commit status (needs the App's `statuses: write` permission); alternatively choose a distinct label such as `hive/auto-merge`. Distinct from the [App self-merge sweep](#app-self-merge-sweep-auto_merge), which needs no label and no human queuer. | | `project.repo_policies[].auto_merge` | effective `false` below L6; unset = `true` at L6 | Per-repo off switch. Switching to L6 turns this on for every active repo; owners can toggle repos afterward. `false` lets Hive open PRs for that repo but blocks all Hive merge paths (`hive-merge`, App self-authored sweep, and proxy-visible direct REST/GraphQL merge attempts). The dashboard repo-card switch persists this key and takes effect without restart. | diff --git a/src/docs/running-at-level-6.md b/src/docs/running-at-level-6.md index 4ceee9d077..bbab0bb8f2 100644 --- a/src/docs/running-at-level-6.md +++ b/src/docs/running-at-level-6.md @@ -165,7 +165,7 @@ For hosted and self-hosted hives alike, GitHub repository/organization administr | **G5. Require an up-to-date base.** Enable strict required checks/"Require branches to be up to date before merging" on each protected branch. | Green on an older base does not establish green after integration. Verify a PR becomes blocked after a base push until updated/retested. The sweep attempts updates for `behind`; see [sweep](../pkg/github/automerge/automerge_sweep.go). | | **G6. Allow the merge methods actually used.** Settings → General → Pull Requests: allow squash; also allow merge commits if managing release-line forward merges. | The ordinary method is squash; recognized forward merges use merge commits to preserve ancestry. Disallowed methods cause merge refusals. Verify landing method in a test PR and ancestry for a sync PR. See `mergeMethodFor` in [sweep](../pkg/github/automerge/automerge_sweep.go) and [pull requests](../pkg/github/pullrequest.go). | | **G7. Keep fork-run approval deliberate.** Settings → Actions → General → Approval for running fork pull request workflows: choose the trust policy your maintainers can service. **JUDGMENT CALL:** require approval for untrusted fork authors rather than relaxing it to drain a queue. | Unapproved runs are `action_required`, not successful CI. Have a maintainer inspect the workflow/diff then approve runs; verify check evidence appears at the PR head. See `forkRunApprovalReason` in [CI gate](../pkg/github/merge_ci_gate.go). | -| **G8. Test signed-commit requirements end to end.** If your ruleset requires signatures, enable `github.app_signed_commits` in Hive runtime YAML (not a dashboard switch) and test follow-up commits too. | An unsigned follow-up can strand an otherwise green PR. Hive reconciles its own commits, not people's work. Verify GitHub's Verified badge at the latest head and branch-rule acceptance. See [signed reconciliation](../pkg/github/pr_signed_reconcile.go). | +| **G8. Test signed-commit requirements end to end.** If your ruleset requires signatures, enable `github.app_signed_commits` (Settings → Forge App → **Re-author agent PRs as GitHub-signed commits**, Owner role; or in Hive runtime YAML) and test follow-up commits too. | An unsigned follow-up can strand an otherwise green PR. Hive reconciles its own commits, not people's work. Verify GitHub's Verified badge at the latest head and branch-rule acceptance. See [signed reconciliation](../pkg/github/pr_signed_reconcile.go). | ### Test coverage of 90% or better