Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/changed-app-signed-commits-docs.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions src/docs/github-app-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<app_slug>[bot]`, that a `required_signatures` rule accepts.

**DCO.** The mutation takes no author: GitHub stamps its own bot account on the commit (`<app_slug>[bot] <id+slug[bot]@users.noreply.github.com>`). 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 `<slug>[bot]@users.noreply.github.com` sign-off (with or without GitHub's numeric prefix) becomes `<slug>@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.
Expand Down
1 change: 1 addition & 0 deletions src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<app_slug>[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. |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/running-at-level-6.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading