Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Running a hive at ACMM Level 6

For people who operate a hive, Level 6 means unattended merging, not just faster agents. Protect every destination branch with real required tests and coverage checks; aim for 90% or better coverage before enabling automatic merging. Stage repositories individually, keep work creation below CI/merge capacity, and prove your emergency stops work before you need them. Human-authored PRs can merge too. A reviewer comment, a spending limit, and paused agents are not substitutes for a merge stop.

This guide walks through preparation, a weekly routine, and recovery. Start with the merge-path table, configure the five areas below, then use the single pre-switch checklist. After a bad merge, stop further harm first, revert and verify, then demonstrate that a strengthened required check rejects the original change.

Last checked: 2026-10-04 against branch v5, commit 18e4a36e6d81c9e9fcefc6a3dcab8f93b25355e9. Source links name files and symbols rather than fragile line numbers. DOCUMENTED NOT EXECUTED: this is a code-checked guide, not a live deployment trial. JUDGMENT CALL consistently marks operating choices that the product does not establish. Hive does not enforce those choices unless the practice explicitly names an enforcement mechanism.

How directions are given. Every step says where to do it in the dashboard first and gives the config-file setting second. Nothing in this guide needs an API call. Where the dashboard has no control for something, the step says so.

Read this before enabling unattended merges

ACMM is Hive’s AI-native Capability Maturity Model: levels determine permitted automation. Level 6 (L6) is Fully Autonomous, not a release-branch name. An agent is a configured AI worker; a pack supplies a level’s roster, modes and defaults. The governor schedules workers according to workload modes; a cadence is an agent’s wake interval in mode. These definitions and the shipped roster are grounded in the Level 6 pack. scanner has ISSUES_PRS_MERGE; other delivery agents create PRs but the App can merge them independently.

Auto-merge here means Hive initiating a merge without a person doing it, not GitHub’s similarly named feature. A hold is a label-based exclusion from work/merging, including literal hold and the dashboard’s hive-pause/<hive-id> item hold. See labels and control signals; the enforcing predicates are HasHoldLabel, IsHeldLabels and HasExemptLabel in GitHub client.

Which PRs merge without a person?

All answers assume the repository participates in automatic merging, the PR is ready, unheld and non-exempt, GitHub allows the merge, and the path’s checks pass. The common per-repository gate is RepoAutoMergeEnabled in repo policy; below L6 it returns false.

The third route is the human-approved queue (normally lgtm): an authorized merger/owner queues someone else’s PR; the sweep rechecks that authorization. See handleQueuePRAutoMerge in dashboard API and trySweepQueuedPR in sweep. A bare lgtm from an arbitrary account is not authorized queueing.

What waits, and what releases it?

Does the Hive reviewer stop a merge?

Default: no automatic guarantee. The reviewer is advisory. Its requires_human text is not read by the App sweep. With review.require_approval: true, the scanner eligibility path requires aggregate approval at the same head SHA; absent artifacts or a non-approved verdict stop that path. It does not add a review gate to the App sweep or replace GitHub branch rules. Dispatch fan-out also has its own enabling conditions. See classifyMergeEligibility in eligibility, PlanDispatch in review dispatch, and sweep.

The policy matrix describes the same distinction: reviewer verdicts alone are not universal merge stops, and promotion does not automatically release level holds. Use GitHub rules or an actual hold for a safety guarantee.

Label discipline

Before L6, map your repository’s labels to Hive’s gates. In the dashboard, start with Settings → Labels, Settings → Repos, Governor Config → Hub, and the repository-card legend. Compare them with the repo’s GitHub labels and lifecycle/Prow rules. Where a setting has no dashboard control, use the config file with the deployment operator. Hive ships defaults, not a universal workflow: map your existing labels or opt out of conflicting behavior before enabling unattended work. #10537 illustrates the collision between a repo’s triage/accepted/needs-human workflow and Hive’s /hive approve transition to approved-direction.

Config keys to cross-check: project.issue_filter.require_labels, project.issue_filter.reporter_trust.untrusted_require_labels, governor.labels.exempt, governor.labels.automerge, github.self_authorization_hold, github.reporter_trust_hold, per-repo project.repo_policies[].{auto_merge,self_authorization_hold,reporter_trust_hold}, hub.contribute_*labels, governor.claims.*, review.human_decision_label, dashboard.issue_bands.*, and work_source.{linear,jira}.hold_labels (under governor in runtime YAML).

Verify the mapping with canaries: a held item stays held, an accepted issue enters the intended queue, an unreviewed issue stays out, and repo bots do not undo each other’s decision labels. Generic GitHub holds use substring matching (threshold also holds); Linear holds use substring matching, Jira holds use exact configured labels, and GitHub Projects carries labels without an adapter hold gate. Do not assume identical enforcement across sources. Sources: label reference, maintainer commands, GitHub predicates, issue labels, un-park, claim config, progress labels, remainder sweep.

Getting ready to switch

GitHub settings

For hosted and self-hosted hives alike, GitHub repository/organization administrators configure these on GitHub, not the Hive dashboard. In these rows, GitHub enforces its rules; Hive does not enforce the recommended policy choice. The source describing Hive’s interaction is given per row.

Test coverage of 90% or better

T1. Make the 90% target a real CI gate. In each repository’s CI workflow, measure coverage using its native test tooling, save the report as an artifact, and fail below 90%; make that exact job a required GitHub context and declare it in Hive’s required-check set below. Without both, a flattering badge or an optional red coverage job does not protect L6. Verify by opening a PR whose measured coverage falls below the floor and checking that the App cannot merge it. The project’s 90% target is only reported by the advisor, not enforced by Hive as a coverage percentage; CI enforces your configured floor. Sources: advisor code, commit CI, eligibility.

T2. Keep an 82%-covered repository out of auto-merge while improving it. Turn its repo-card auto-merge switch off; use quality work to add behavior/regression tests for uncovered risk, human-review those changes, then measure again in CI. Enable after the 90% target and branch gates are demonstrated. This staging choice is JUDGMENT CALL, not a Hive enforced readiness rule. Verify increasing report coverage and a regression test that fails on the old broken behavior. The quality lane is available in the pack; the switch is enforced by repo policy.

T3. Cross-check the reporting input. The coverage number to trust is the repository’s CI report with its denominator/exclusions, not an agent’s prose. HIVE_COVERAGE_BADGE_URL supplies the dashboard measurement: self-hosters set it in their deployment environment (not dashboard); hosted operators ask the hub operator to set it. Verify the badge agrees with the report. It is a reporting input, not a merge floor. See coverage collector and advisor inputs.

Direct answers about checks:

• Failed test: does Hive still merge? No if it is a required gating check; yes, possibly if it is optional and GitHub allows merging.
• Failed coverage job: does Hive still merge? No if required; yes, possibly if optional. The scanner explicitly permits optional-only red when an operator-declared required set exists and GitHub reports mergeable (onlyOptionalRed). A report uploaded successfully without a failing floor does not block a merge.
• No check results: does Hive merge? The App sweep can say yes after its age/expected-check and GitHub mergeability gates; GitHub protection is essential for missing required contexts. The merge-request path says no to zero statuses/checks/workflow runs unless the repo is explicitly in auto_merge.no_ci_ok. A neutral or skipped observed check is also accepted by the shared evaluator, so keep required gate workflows executing meaningful tests. Missing required contexts block on the merge-request path; on the App sweep, the evaluator records MissingRequired but its green result does not itself reject that list. GitHub’s required-check rules must supply the missing-context block there. Do not rely on the Hive declaration alone. Unapproved or failed workflows that produced no jobs are also checked on the merge-request path.

These are path-specific, not an “all CI green” promise: see commit CI, sweep, CI gate, and eligibility.

Knowledge accumulation

A bead is an agent’s persistent work-ledger entry. The default hourly bead synthesizer classifies closed beads into wiki facts. It is not merged-PR fact extraction; that old pipeline was never wired. Collection can run while priming is off. The primer selects knowledge for an agent’s next kick (work prompt). See knowledge boot, synthesizer, and knowledge curator reference.

Hive settings

Both hosting types use the same spoke dashboard for owner-authorized changes. “Runtime YAML” below means the effective persisted config, not merely a seed ConfigMap; see config layering. Self-hosters manage that file and restart their service; hosted operators ask the hub operator for file/environment/restart changes they cannot perform. Never run repository tests in a live hive to verify configuration.

Each row is a separate practice. Except where marked, the recommendations address the cited shipped behavior; they are not readiness checks that Hive automatically applies.

ClankeR settings

ClankeR is the contributor relay offering external compute to a hive. A trust tier is the contributor profile’s server-side standing, distinct from reporter trust and dashboard access roles. Controls below are under Governor Config → Hub on the hive serving /contribute, also exposed on its contribution admin page. They are not the unrelated central hub’s global settings. Hosted owners use that hive’s admin UI; self-hosted owners use their own dashboard. All are owner-controlled; see Hub config API and relay admin reference.

C6b. Rehearse individual revocation. JUDGMENT CALL: owner uses Operations → Connected clankers → Revoke for an unsafe contributor, and verifies it cannot reconnect. Stop any continuing workload separately and hold/disable merging for its existing PRs; revocation is not a rollback. Undo by deliberately restoring an authorized tier. Hive enforces the revoked-profile connection gate, not incident resolution. See handleAuthResponse in connection admission and trust reference.

Model/effort restrictions apply at the next connection, queue restrictions at the next build. Do not infer that changing them stopped a task already running; see relay reference and connection admission.

Notification hygiene

JUDGMENT CALL: do not make every maintainer watch every Hive write. Comments, labels, claims, reviews, merge messages, un-park notices and work-source activities create continuous noise at L6. Keep actionable alerts assigned to an operator; mute routine chatter, not incident signals.

GitHub Issues/PRs and Projects-backed work. In GitHub’s repository Watch → Custom settings, choose needed event types rather than all activity; use participation/mentions and individual thread subscriptions for focused attention. Filter mail from notifications@github.com by the configured App actor (for example hivecommons-hive[bot], in X-GitHub-Sender) and inspect hidden body markers when your mail client exposes them: , , , , , . Not all markers use the hive: prefix. Unsubscribe from ownership-only threads. Projects is a read source; Hive’s GitHub writes land on backing issues/PRs.

Linear. In Linear’s notification preferences, scope notifications for the Hive app user, delegated/assigned issues, mentions and relevant teams/projects. The agent integration posts as the app (actor=app) and can write thought/action/response session activities, comments/issues and PR links. In Hive Settings → Work Source, narrow Linear enumeration using assigned-only, team states, cycles, projects and hold labels (work_source.linear.*, under governor in runtime YAML). There is no source-neutral Hive mute for Linear session activity.

Jira. In Settings → Work Source, narrow project keys, JQL and hold labels (work_source.jira.*, under governor in runtime YAML). The v5 adapter reads Jira; generic WorkSource is read-only and source-neutral claim/comment/transition writes are not pluggable. If helper writes are enabled later, configure Jira’s project notifications for the credential account; do not assume Hive supplies a Jira-side mute.

Run stages and Wavefront. These additive sources list internal stage/graph work and record receipts; they do not themselves create source-native comments/labels. Noise generally appears on the GitHub issues/PRs opened for that work, so apply the GitHub guidance.

Hive chatter controls. Start in Governor Config → Advisory, Security → PR Review, and Hub; use the runtime config with the deployment operator for controls not exposed in the dashboard. Tune governor.advisory.update_interval_s and governor.advisory.target for digest cadence/destination. Leave review.post_comments off unless public reviews help humans; bound repeat notifications with review.combined_perspectives, review.max_perspectives_per_pr, review.max_reviews_per_head, and per-repo review.revise_repos. Bound duplicate-sweep comments with duplicate_sweep.post_comments/max_comments; turn claim comments off with governor.claims.comment: false. Respect the un-park action cap and repo label-workflow mapping rather than relying on email filters to hide conflicting automation. hive/advisory remains excluded from actionable work.

Verify a routine claim/review no longer floods unrelated maintainers, while a test incident alert and a direct mention still reach the responsible person. Sources: integration guide, work-source providers, work sources, Linear agent, configuration, claim config, un-park.

Readiness, staged switching and confirmation

R1. Use readiness numbers as evidence, not permission. While at L5, open the dashboard’s Advisory section and read the ⬆️ Ready to level up? card. Its checklist covers: quality agent present, coverage ≥90%, ≥12 consecutive non-red default-branch runs, merge success ≥95%, actionable issues ≤10, holds ≤5. These thresholds are only reported, not enforced or configurable. Verify against each repo’s CI and reviewed changes, not just a hive-wide aggregate. They do not measure security, test adequacy, production outcomes or knowledge accuracy. At L6 the advisor reports ready/stay because there is no higher level, not because all readiness criteria remain satisfied. See advisor, input collection.

R2. Stage without an all-repos merge window. JUDGMENT CALL: an owner should use the following sequence; Hive enforces the pause/repo switches, not this rollout discipline. The level action reconciles roster, pack fields and cadences (operator-owned cadences survive), activates L6 merge capability, and enables auto-merge for active repos. It does not add strong CI, change installation permissions, validate coverage or automatically release old holds. Sources: pack API, repo policy.

1. Pause all managed repositories with repo-card Pause before applying Level 6. These pauses remove them from active repositories; do not merely disable auto-merge beforehand, because promotion re-enables active repos.
2. As owner, click the ACMM level badge in the dashboard’s top bar (or ACMM Eval → Change level), choose Level 6 and Apply. No notice follows, so check the result yourself as in R3.
3. While repos remain paused, switch Auto-merge off on every repository card, then look at each card again to confirm it stayed off.
4. Resume just qualified repo, then enable its Auto-merge as verified owner. Other repos stay paused or are resumed with Auto-merge explicitly off.
5. Verify an eligible test PR merges in the chosen repo; verify another repo rejects merging. Review any old held PR separately before removing its hold.

R3. Confirm intent after every switch, restart and upgrade. On the dashboard, check three things: the ACMM level badge in the top bar shows the level you intended; each agent’s card shows the mode, cadence and paused state you expect; and each repository card shows the Auto-merge and paused state you set. Then open Audit Log and confirm that merges are appearing, or have stopped, as you intended. If you keep settings in the config file, compare it with what the dashboard shows. Use a harmless held test PR to confirm it stays held, then a qualified canary to confirm the intended path works. Without read-back, a saved level alone can hide reconciliation or persistence failure. Hive reports state and errors; this verification discipline is JUDGMENT CALL. Sources: pack API, sweep startup, config layering.

Do not rely on a promotion notice: the checked dashboard defines maybeShowLevelAutoMergeActiveModal but the Apply flow does not call it. This differs from references promising a notice. Check state yourself; see dashboard.

Pre-switch checklist (complete per rollout)

These are confirmations of the practices above, not additional product gates.

• Real weeks at L3–L5 produced reviewed PRs matching your judgment; no calendar interval is enforced, and “not surprised” matters more than elapsed time.
• GitHub installation scope/permissions and every merge destination’s rules checked; App cannot bypass critical tests/coverage. Green CI genuinely means safe to ship, not just a passing harness.
• Each proposed repo meets the 90% coverage target with demonstrated failing gates; below-target repos remain excluded. Advisor readings and their limitations recorded.
• Per-repository opt-out decided and applied: Level 6 is not all-or-nothing. Each repository card’s Auto-merge switch is set deliberately (off for repos that are not ready or must stay human-merged; project.repo_policies[].auto_merge in config), and a test PR in an opted-out repo was refused while agents kept proposing work there. Remember that re-applying Level 6 re-enables auto-merge for every active repo, so opted-out repos are paused during the switch (R2) or re-checked afterwards (R3).
• Reporter-trust posture explicitly decided before promotion. For public issues, trust is on with the intended association set; decide specifically whether CONTRIBUTOR belongs. Demonstrate admission and PR-side holding.
• Knowledge priming enabled and actual prompts inspected; release/test/rollback constraints are accurate. Any relied-on checkout instructions demonstrably reach agents.
• Hive repo scope, required contexts, proposal/plan decisions, cadence, token budget, paused lanes and alert delivery reviewed.
• Issue claims enabled (governor.claims.enabled) with TTLs that fit real task length; a claimed test issue was withheld from agents and released on lapse/unclaim. Humans know to hivectl claim before starting on an item that agents could also pick up.
• ClankeR filters, model/effort admission, trust/roles, independent queueing and suspension tested.
• Repository labels mapped to Hive gates; acceptance, hold and un-park canaries do not conflict with lifecycle/Prow automation.
• GitHub/work-source notifications narrowed; routine chatter muted without hiding direct mentions or actionable incident alerts.
• Emergency brake understood: item hive-pause/<hive-id>/hold, repo merge-off, and level step-down. Agent pause and budget exhaustion are not merge stops.
• Outreach remains held at L6; human review is still expected, not removed by a setting or promotion.
• Staged rollout and fresh read-back/canary prepared; old holds will not be batch-released blindly.

Running week to week

W1. Review a small sample and trends every week. JUDGMENT CALL: name a responsible operator and record these readings in an operator log. Hive does not enforce a weekly review or a sample size. Without outcome review, green checks can repeatedly ship the wrong behavior. Verify corrective actions from the last review actually landed. Sources for the displayed mechanisms: fleet health, merge audit, governor budget.

W2. Slow creation before accelerating everything. When new issues/PRs outpace merges and oldest queue age rises across successive windows, lengthen creator cadences in Agent settings → Cadences; keep reviewer capacity available and repair CI bottlenecks. The pack already omits/pauses architect/guide work generation when busy/surging and keeps reviewer at 30 minutes. Verify lower arrivals and falling queue age after the change. Hive enforces cadence, does not enforce arrival/merge balance. Evidence: pack’s measured tuning comment.

W3. Use an actual hold for change. Add literal hold on GitHub or use the dashboard item’s Hold action (PR or issue) before a decision-sensitive change becomes eligible. Authors should open unfinished PRs as drafts, not ready PRs with a “please don’t merge” comment. Verify held/draft status and exclusion from eligibility. Hive enforces these states; prose requests, lack of lgtm, reviewer text and needs-human alone are not universal merge stops. The hold matcher is substring-based (threshold also contains hold); provenance hive/<id> is not a hold. See client predicates, item hold API, eligibility, sweep.

When something goes wrong

Stops, smallest to largest

S1. Choose the stop that closes the dangerous path, then read it back. Do not substitute paused workers for revoked merge authority. This practice follows the distinct enforcing paths cited below. Confirm in the dashboard’s Audit Log that no new merges appear after a repo merge stop, accounting for a request already in flight; a stop cannot undo a completed merge.

These controls stop Hive, not a separate GitHub bot or a maintainer manually merging. For an immediate repo-wide incident boundary, a GitHub administrator can also revoke/suspend the App installation’s access; coordinate restoration and verify credential failures, rather than silently weakening branch rules. JUDGMENT CALL: use this larger boundary if Hive’s runtime state cannot be trusted. No Hive setting enforces that incident policy.

After a bad merge

S2. Contain, reverse, prove prevention. JUDGMENT CALL: use this ordered recovery procedure. Hive does not automatically enforce it. Perform changes with an authorized maintainer and keep the incident record on GitHub; verification is the artifact from each step, not “agent says fixed”.

1. Prevent further harm. Turn the affected repo’s Auto-merge off; if scope is unknown disable all repos or lower the level. Pause harmful workers/contributions too. Confirm persisted switches and stopped merge activity using S1. Do not merely exhaust a budget or pause agents.
2. Record the PR’s head and merge SHA, the merge’s entry in the dashboard’s Audit Log, the required-check results on GitHub, and the deployment revision. Work out whether the sweep, the scanner, a queued merge or another actor landed it. Sources: merge audit, relay merge.
3. Revert through a human-reviewed PR (or use the project’s authorized emergency procedure), run CI, and verify the destination branch no longer contains the bad behavior. If deployed, roll back the application too and verify the running revision plus the failing user scenario; a Git revert alone is not a deployment rollback. For Hive itself, use the digest-verifiable rollback runbook.
4. Determine the missed protection: absent context, optional coverage, stale base, unchecked integration behavior, bypass, or incorrect scope. Record an accurate knowledge fact and correction so future workers do not repeat the assumption.
5. Add or strengthen a required check before restoring automation. Run the new regression/check against the bad PR’s exact head (it must fail) and the reverted/fixed head (it must pass). Verify the context is required on GitHub and in Hive’s declared set, with no App bypass. Then restore the qualified repo. CI gates, not the recovery prose, enforce future merging: commit CI, CI gate.

When work is stuck

S3. Repair the blocking system, not the symptom. Identify the row below from the reason the dashboard or GitHub shows before changing policy; verify recovery at the same PR head or a deliberately repaired head. Hive reports/enforces the cited gates, not an obligation to make every queue item merge.

S4. Step down when confidence in unattended landing is lost. JUDGMENT CALL: repeated bad merges, unavailable required CI, or inability to explain active authority warrant L5 while investigating. Owner changes the level through the level/pack control; verify as R3. Hive enforces repo merge-off below L6, so already-open PRs lose Hive automatic merge eligibility; it does not revert their commits or retroactively add a level hold to every old PR. Subsequent non-outreach agent PRs at L3–L5 receive the level hold; outreach stays held at all levels. Manual/other-bot merges remain outside this stop. Promotion later leaves old holds intact unless explicitly released, and enables active repos again. See repo policy, shouldHoldAgentPR in eligibility, level hold, pack API.

Maintainer review of this guide and its promotion belong to #10515, not an agent review. Until that sign-off, retain the notice and the index’s awaiting-review label.