Workspace-Level Settings

Workspace-level settings are organization-wide agent policies that apply across every repository in your Obvious workspace. Unlike per-repo configuration in .obvious/config.yml, these settings are managed through the Obvious Settings UI or API and cannot be overridden at the repository level.

Use workspace-level settings when you need consistent human-oversight guarantees across all your codebase — for compliance requirements, audit trails, or organizational policies that must hold regardless of which repo an agent is working in.

Available Settings

requireHumanMerge

When enabled, agents complete all upstream work — writing code, running CI, conducting reviews — but cannot merge a pull request. When the agent reaches the merge step, it stops and hands off to a human with explicit instructions to complete the merge.

Agent behavior with requireHumanMerge active:

• Pushes the branch
• Creates the PR
• Waits for CI and runs or responds to code reviews
• Stops before merging
• Surfaces the merge command and PR link for a human to complete

When to use it: Teams that require a human sign-off as the final gate on every code change. Common in regulated industries, security-sensitive codebases, or any team that wants an accountable human at the end of every merge.

requireHumanCreatePR

When enabled, agents push their branch and provide a GitHub compare URL, but cannot open a pull request. A human must create the PR from that URL.

Agent behavior with requireHumanCreatePR active:

• Commits and pushes the branch
• Outputs the GitHub compare URL for the human to use
• Does not call gh pr create

When to use it: Teams that want humans to control the PR surface — setting reviewers, labels, milestones, or draft status — rather than delegating that to the agent. Also useful when PR creation triggers downstream automations that should only fire after human review.

How Enforcement Works

Both settings are enforced through three independent layers. This layered approach means the policy holds even if an individual layer has a gap — it is not purely prompt-driven.

Layer 1 — Prompt-Layer Capability Blocks

Agent prompts are constructed with explicit capability restrictions when a policy is active. The agent is instructed, at the system level, that it does not have permission to perform the blocked action. This is the first and most visible layer: the agent knows from the outset that merging or PR creation is outside its scope for this workspace.

Layer 2 — Prompt Gates

Before every site in the agent workflow where a merge or PR creation would occur, a conditional instruction checks whether the relevant policy is active. This is a fine-grained guard — even if an agent were to reach that decision point unexpectedly, the gate re-checks the policy and redirects behavior before the action is taken.

Layer 3 — Tool-Layer Backstop

The computer-operations handler — which executes shell commands in the agent sandbox — intercepts gh pr merge and gh pr create commands directly. If a policy is active:

• The command is blocked at the execution layer
• The handler returns an error
• The error includes guidance on what the agent should do instead (e.g., surface the merge link to the human)

This means even if prompt-level instructions were somehow bypassed or misinterpreted, the tool itself will not execute the blocked action.

How This Differs from config.yml

	Workspace-Level Settings	config.yml
Scope	All repositories in the workspace	Single repository
Where configured	Obvious Settings UI or API	.obvious/config.yml in the repo
Can be overridden per-repo	No	N/A
Primary use case	Organization-wide security and compliance policies	Repository-specific workflow preferences
Examples	requireHumanMerge, requireHumanCreatePR	Merge method, base branch, CI commands, preview URLs

Use config.yml to express how a particular repository operates. Use workspace-level settings to express what agents are never allowed to do, regardless of repository.

Configuring Workspace Settings

Workspace-level settings are managed through Settings → [Your Workspace] in the Obvious UI, or via the Obvious API. They are not file-based and do not live in any repository.

Changes take effect immediately across all repositories and all agents running in that workspace.