glab-govern

# glab govern Configure and operate GitLab's experimental AI agent governance support for external agents. ## Safety and scope - Governance sync is an external data upload, not just local diagnostic logging. Uploaded events can include user prompts, tool-call arguments (commands, file paths, edits; replaced with a marker over 8 KB), outcomes/errors/durations, model, and token usage. Tool output and response text are not uploaded. Do not assume this excludes secrets in prompts or arguments. - `glab govern setup` installs Claude Code `Stop` and `SessionEnd` hooks in `~/.claude/settings.json` and, by default, a durable fallback periodic sync job on macOS/Linux. Obtain approval for both the settings change and transcript upload scope before running setup. - Use `--no-fallback-sync` to install hooks without installing or replacing the fallback job. It does not remove an existing job or clear stored agents; verify those separately before treating the machine as hooks-only. The hooks still upload audit events. This is not a no-upload mode. - `--agents codex,cursor` enables transcript discovery without agent hooks, including sessions from before enablement, for repositories on GitLab hosts you are logged in to. Enabling these agents needs explicit approval for historical uploads and all eligible repositories, not just the current checkout. - This integration does not automatically govern Hermes. OpenCode hook-recorded sessions are supported and read through `opencode export`; setup's installed hooks are for Claude Code. - Prefer `glab govern doctor` for read-only diagnosis. Help inspection does not authorize running setup, sync, uninstall, or changing host services. ## Setup and verification ```bash # Inspect the experimental surface without changing settings or uploading transcripts glab govern --help glab govern setup --help glab govern audit sync --help glab govern doctor ``` After reviewing the target host, visible GitLab actor, eligible repositories, and upload contents, choose exactly the approved setup scope: ```bash # Hooks plus the default macOS/Linux fallback job glab govern setup # Install hooks without installing/replacing the periodic job (existing jobs remain) glab govern setup --no-fallback-sync # Explicitly include Codex and Cursor historical/local sessions glab govern setup --agents codex,cursor ``` `--agents` and `--no-fallback-sync` are mutually exclusive; glab rejects combining them, even with `--agents ""`. Codex/Cursor discovery has no agent hooks and uses the fallback periodic sync. Use `--yes` only after the underlying change/upload scope is approved. Setup is rerunnable: existing hooks are not duplicated and ordinary setup replaces the fallback job. Omitting `--agents` preserves the stored agent list, which the confirmation prompt names; a later plain setup can restore background discovery for those agents. An explicitly supplied `--agents` list replaces the stored list; `--agents ""` stops Codex/Cursor discovery. Review the retained agent/upload scope before rerunning setup. Inspect the settings/job files and rerun `glab govern doctor` after changes. ## Fallback periodic sync On macOS, setup installs `~/Library/LaunchAgents/com.gitlab.glab-govern-audit-sync.plist`. On Linux it installs the user timer `~/.config/systemd/user/glab-govern-audit-sync.timer`. The fallback job runs `glab govern audit sync --all` every 30 minutes (also 5 minutes after boot on Linux) until removed. It uses stored credentials and the glab configuration directory selected at setup. Windows has no fallback periodic sync. `--all` sends each recorded/discovered session to its own project and host, not simply the current checkout or one `--repo` target. It marks sessions complete after 24 hours of inactivity. Claude Code sessions are paused while the glab Stop hook is missing. `doctor` reports fallback configuration, the last-run result, and whether the job's configured glab binary reports a different version from the running CLI. A drift warning recommends rerunning setup; that is a settings/job change requiring the same upload-scope approval, not an automatic repair. A never-synced session inactive for 89 days is not uploaded. If an instance does not yet accept an agent's sessions, those sessions are skipped permanently; upgrading the instance does not backfill them, while sessions created after the upgrade are eligible. ## Manual audit sync For current-session sync, first verify the intended actor, host, and project: ```bash : "${GITLAB_HOST:?set GITLAB_HOST to the intended GitLab hostname}" glab auth status --hostname "$GITLAB_HOST" glab api --hostname "$GITLAB_HOST" user # Upload only after the target and transcript scope have been approved glab govern audit sync --repo "https://$GITLAB_HOST/my-group/my-project" ``` The normal target comes from `-R/--repo` when supplied (namespace path, full URL, or Git URL), otherwise the current checkout's Git remote. Do not run from an arbitrary checkout. Use `--complete` only when the session should be completed. `--silent` hides output for hooks; avoid it during initial verification. Do not use `--all` as a harmless connectivity test. Agent limitations: - OpenCode does not send prompts/responses; an outcome is included only if the tool call was complete when first synced. - Codex tool outcomes are reported as `completed`, not proven successful. - Cursor sends only prompts and tool calls, timed by transcript modification; it has no outcome/token/timestamp records. Ambiguous workspace mappings or file calls outside the inferred workspace cause that session to be skipped rather than uploaded to the wrong project. ## Uninstall and pause ```bash # After approving removal of the local job and agent discovery glab govern setup --uninstall ``` Uninstall removes the installed Claude Code hooks and fallback periodic job, and stops Codex/Cursor syncing; unrelated hooks and settings are preserved. If settings cannot be read, removal of other components can still occur while hook removal fails. Review warnings, repair the settings, and rerun the approved uninstall before considering capture stopped. Verify the resulting settings, absence of the exact job, and `doctor` output. `--no-fallback-sync` is a hooks-only setup option, not a replacement for uninstalling an already-installed fallback job. ## Troubleshooting - Missing hooks: inspect the settings file and the glab executable's non-interactive `PATH`; rerun setup only within approved scope. - Failed auth/connectivity: verify the intended actor using `glab auth status` and `glab api user`; never print tokens or upload a transcript just to test access. - Unexpected uploads: inspect the fallback job, stored host credentials, agent list, and per-session repository mappings. Stop the approved job/hooks before changing credentials or project state. - Wrong project or potentially sensitive prompts/arguments: stop before sync; do not treat outcome labels, omitted responses, or argument truncation as content redaction. ## Command reference See [references/commands.md](references/commands.md) for complete checksum-verified parent, setup, doctor, audit, and audit-sync help.