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
3 changes: 3 additions & 0 deletions src/docs/api-reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

Part of the [Dashboard REST API reference](../api-reference.md); see that page for how auth levels and `pkg/<file>:<line>` source citations are read and checked. Edit this file for routes in this area and run `src/scripts/check-api-reference-citations.sh --fix` to resync citations.

For dashboard instructions and the difference between raw YAML and effective
JSON, see [Editing `hive.yaml`](../editing-hive-yaml.md#view-yaml-or-export-effective-config).


| Method | Path | Auth | Purpose | Source |
|---|---|---|---|---|
Expand Down
3 changes: 3 additions & 0 deletions src/docs/config-layering.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

**Which layer sets this field, and where do I write to change it?**

For deployment-specific paths and an editing workflow, start with
[Editing `hive.yaml`](editing-hive-yaml.md).

Until this document existed, that question was answerable only by reading a
single line of pod boot logs. It cost real time: a GitHub Enterprise hive was
repaired on the **fourth** attempt, after patching the hub's `meta.json`, then
Expand Down
1 change: 1 addition & 0 deletions src/docs/documentation-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und

- [Self-hosted hub deployment](hub-deployment.md) — `HIVE_MODE=hub`, hub storage, heartbeat secrets, and SaaS spoke registration.
- [`CAP_NET_ADMIN` and self-hosted spokes](net-admin-requirement.md) — **Operator:** diagnose fail-closed startup, grant required network capabilities, or understand the explicit advisory-only opt-out.
- [Editing `hive.yaml`](editing-hive-yaml.md) — find the persisted config, choose Settings or YAML, and verify a reload or restart.
- [Config layering](config-layering.md) — how ConfigMap seed, PVC dashboard overlay, and runtime config interact.
- [Operator reference](operator-reference.md) — top-level config blocks, hive flags/env, GitHub token scopes, and image provenance.
- [Running a hive at ACMM Level 6](running-at-level-6.md) — preparation, GitHub/coverage/knowledge/Hive/ClankeR settings, weekly routine, and incident recovery.
Expand Down
110 changes: 110 additions & 0 deletions src/docs/editing-hive-yaml.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Editing `hive.yaml`

Use **Settings** if it has an editable control for your key. If it does not,
change the deployment's YAML. On a hosted hive with no shell or deployment
access, ask the hosting operator to make that change; viewing or exporting the
config does not let you write it back.

## What Settings can change

Search Settings using the full dotted key (for example,
`governor.labels.stage.engine.mode`). The [Settings guide](settings.md) lists
controls by tab, and the [operator reference](operator-reference.md#configuration-blocks)
explains the YAML keys. Common examples:

| Settings tab | Example editable YAML keys |
| --- | --- |
| General | `acmm_level` |
| Labels | `governor.labels.stage.engine.mode` |
| Repos | `project.repos`, `repos.<repo>.parent_autoclose` |
| Budget | `governor.budget.usd` |
| Dashboard | `dashboard.port`, `dashboard.subscription_gauge_header` |

The [Settings parity allowlist](../pkg/dashboard/settings_parity_allowlist.txt)
records per-key exceptions to the dialog coverage check, with comments on why
an exception exists. It is not a permissions list or an exact list of all
file-only keys: the check looks for YAML key references in the dialog, and some
keys have read-only displays or are set through another control. Check for an
editable control on your running version.

**`review.analysis_factcheck.*` is YAML-only.** The review controls in
Settings do not enable it. If you only have the dashboard, send the hosting
operator the [TechDocs YAML example](workflows/techdocs-assessment.md#independent-fact-check-before-a-person-reviews-optional)
with your drafter, reviewer and qualifying label; do not send your whole YAML.

## Find the file that survives restart

| Deployment | First-boot input | Where to edit an existing hive |
| --- | --- | --- |
| [Kubernetes](kubernetes-deployment.md) | `hive-config` ConfigMap, key `hive.yaml`, staged at `/etc/hive/hive.yaml` | `/data/hive.yaml.runtime` on the persistent volume. On newer manifests `/etc/hive/hive.yaml` links there; on older ones it is a copy. |
| [Podman / Quadlet](quickstart-podman.md) | `~/.config/hive/hive.yaml` (rootless) or `/etc/hive/hive.yaml` (rootful), mounted at `/etc/hive/hive.yaml` in the container | `/data/hive.yaml.runtime` in the `hive-data` volume. The seed mount is read-only. |
| [Docker Compose](quickstart-docker-compose.md) | `src/hive.yaml` in the checkout (`./hive.yaml` relative to `src/docker-compose.yaml`), mounted at `/etc/hive/hive.yaml` in the container | `/data/hive.yaml.runtime` in the Compose `hive-data` volume. The entrypoint can copy it over the bind-mounted file at boot. Docker Desktop on macOS follows this same rule. |
| Native `hive` binary on macOS or Linux | `/etc/hive/hive.yaml` by default, or the file specified at launch | The same file. For example, `hive --config ./hive.yaml` uses the file relative to the process's working directory. |

The repository's [macOS LaunchAgent example](../../launchd/com.hive.plist.example)
runs the agent supervisor, not the native `hive` server. It does not set the
server's config path.

`HIVE_CONFIG` sets the binary's default path; an explicit `--config` takes
precedence. The container entrypoint also honors `HIVE_CONFIG` and can redirect
the binary to the persisted file when the seed mount is read-only. For a
running deployment, check `metadata.persisted_path` in the JSON export or the
`boot: config source of truth` log, which also shows `loaded_from` and the
symlink-resolved `boot_source`. An older volume can still boot from
`/data/hive.yaml.bak` if the runtime file is absent. Do not delete either file
to force Hive to pick up a seed edit.

## View YAML or export effective config

On the **hive's** dashboard, sign in as an owner and open the avatar menu:

- **View hive.yaml** (`GET /api/config/download`) shows the raw YAML read
from `HIVE_CONFIG` or `/etc/hive/hive.yaml`. The viewer lets you copy it;
the endpoint also serves it as an attachment. It is not the merged config
and can contain secrets. Do not paste it into an issue or share it publicly.
- **Export effective config (JSON)** (`GET /api/config/export`) shows the
in-memory `effective` config. `layers` shows the seed, dashboard overlay,
per-agent overrides and `config.env`, with paths and presence markers.
`side_files` shows adjacent inputs such as prompt templates, restrictions
and sidebar layout, not YAML merge layers. `provenance` reports field origins
from the layer merge; check `effective` to see what the process is actually
using. The export redacts secret-looking values, but review it before
sharing. It is neither an import file nor a [disaster recovery backup](backup-restore.md#config-export-is-not-a-backup).

On a new Kubernetes volume the dashboard overlay is merged over the ConfigMap
seed to create the runtime file. After that, the runtime file is the entrypoint's
boot input. The Go loader can still apply selected dashboard-overlay fields and
per-agent overrides, and `config.env` can pin certain values. See
[configuration layering](config-layering.md) for the precedence and exceptions.

## Edit, validate, and apply

1. Plan a maintenance window for manual edits. Back up the files you will
change, keep the copies private, and coordinate with anyone saving
Settings: a save from the running hive can overwrite a manual edit.
2. Change only the intended key in the persisted YAML, preserving permissions
and any environment references. Update the existing YAML block rather than
adding a duplicate. On Kubernetes, if `/data/hive.yaml.dashboard` already
supplies an overriding block, update the field in that block too. For
example, the Go loader can take `review` as a whole from the overlay, so a
runtime-only `review.analysis_factcheck` edit can be masked even after a
restart. Do not replace the secret-free overlay with the runtime file.
3. Validate with the deployed version of `hive`, in the same environment
and with the same config layers available: `hive validate -config /path/to/hive.yaml`
(substitute the edited YAML path). This loads and validates the config
without starting another hive. Do not restart on a validation error.
4. Check when the setting takes effect. Settings saves may apply immediately,
on a later sweep, or only at startup, depending on the field. For example,
the stage engine reads `governor.labels.stage.engine.mode` on its next
pass, while the dashboard listens on a new `dashboard.port` only after a
restart. For a manual edit, Hive watches the **loaded file**, not every
input in the export. Check for `config reloaded from file` or
`config reload failed` in the logs. A reload can update live readers but
cannot reinitialize every boot-time service. If the edited file is not
the watched file, the setting is startup-only, or live reload is not
documented for the setting, restart through your deployment manager
without replacing the data volume. For changes to process environment or
mounts, reapply the deployment so the process receives them.
5. Verify the effective value in a fresh JSON export (or the setting's
runtime behavior) and check startup or reload logs. If the value did
not change, check for an overriding layer before editing again.
2 changes: 2 additions & 0 deletions src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ For the full centralized environment variable table, including hub, backup,
inference, deployment, contributor, and legacy helper-script variables, see
[Environment variable reference](env-vars.md).

For where the file lives and how to apply changes, see [Editing `hive.yaml`](editing-hive-yaml.md).


The reference is organized into the sections below. Existing links to this page remain available here.

Expand Down
2 changes: 1 addition & 1 deletion src/docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This page is the starting point for the dashboard's **Settings** tabs. It has on

Every setting on a Settings tab has a small **?** mark next to its name. Rest the pointer on it, or move to it with the Tab key, to see a short explanation of the setting. Click it, tap it, or press Enter on it to open the page that explains the setting in a new tab. When a setting has its own guide, the mark opens that guide; otherwise it opens this page at the tab's entry. Clicking a mark never changes the setting.

For the dashboard's other sections, see [Dashboard sections explained](dashboard-sections.md). For which file a saved setting is written to, see [Spoke configuration layering](config-layering.md).
For the dashboard's other sections, see [Dashboard sections explained](dashboard-sections.md). If a key has no editable control, see [Editing `hive.yaml`](editing-hive-yaml.md) for file locations and reload behavior.

## Linking to a setting

Expand Down
5 changes: 4 additions & 1 deletion src/docs/workflows/techdocs-assessment.md
Original file line number Diff line number Diff line change
Expand Up @@ -453,7 +453,10 @@ file. Its findings go back to the drafter, which revises the same branch, for a
number of rounds.

It is off by default and the model does not turn it on: the qualifying agents and labels are
the operator's choice in `hive.yaml`. For a hive bound to `cncf/techdocs`, for example:
the operator's choice in `hive.yaml`. There is no Settings control for this block. See
[Editing `hive.yaml`](../editing-hive-yaml.md) for where to make the change and how to
apply it, including what to ask for if you only have the hosted dashboard. For a hive
bound to `cncf/techdocs`, for example:

```yaml
review:
Expand Down
Loading