Build a policy-controlled deployment automation control plane #59

Context

Issue #57 adds the narrow operator API needed to promote the OpenAgents production fleet, and OpenAgentsInc/openagents#12 adds its CLI client. Those issues solve an immediate operational gap. They must not become an accidental multi-tenant deployment design.

OpenAgents will also need a repository automation system in the shape of GitHub Actions: users and agents run workflows, produce artifacts, request deployments, pass policy checks, obtain protected-environment approval, and receive durable results. That system may reuse Forge execution machinery, but it needs a tenant-safe control plane and authority model of its own.

Goal

Design and implement policy-controlled deployment runs for user repositories and environments. A deployment request should describe an immutable desired outcome. Durable workers should evaluate policy, run checks, wait for approval when required, execute through an environment provider, and record a complete event and receipt history.

Do not expose the OpenAgents fleet operator scope to repository workflows. deployments:promote remains a platform-operator authority for OpenAgents-owned infrastructure.

Domain model

Define durable records for:

• Environment: a repository-scoped logical target such as preview, staging, or production, with protection policy, provider binding, concurrency policy, and retention settings.
• Deployment request: repository, exact commit and artifact identities, environment, creator principal, source workflow, idempotency key, and requested time.
• Deployment run: the admitted execution attempt, immutable input digest, state, provider receipt, timestamps, and terminal result.
• Approval: approver principal, policy rule, decision, timestamp, and request digest. An actor cannot approve a request when policy requires separation of duties.
• Check result: named check, exact input identity, status, evidence link or digest, and validity window.
• Deployment event: append-only state transition suitable for UI timelines, API polling, webhooks, and audit export.

Use explicit states such as requested, checking, waiting_for_approval, queued, deploying, succeeded, failed, cancelled, and superseded. Define legal transitions in one context module and enforce them transactionally.

Authority model

Support distinct principals with least privilege:

• A human repository member may request deployments when repository policy permits it.
• A workflow identity may request deployment only for its repository, source ref policy, and named environment.
• An environment approver may approve only environments assigned to that approver or team.
• A provider credential may execute only against its configured environment binding.
• A platform operator may administer providers and recover stuck control-plane runs without acquiring tenant repository secrets.

Introduce repository- and environment-bound scopes rather than a global write scope. Short-lived workflow grants should identify the run and exact audience. Recheck current repository membership and environment policy at sensitive transitions. Keep tenant production approval separate from OpenAgents platform production promotion.

API and CLI shape

Provide a versioned API for:

• Creating, listing, viewing, and cancelling deployment requests and runs.
• Listing environments and reading their protection requirements.
• Approving or rejecting a request.
• Publishing check results from trusted workflow identities.
• Streaming or polling append-only deployment events.

Use exact commit and artifact digests, idempotency keys, optimistic preconditions, bounded pagination, typed errors, and stable JSON. Emit webhooks only from durable committed events and sign them per tenant.

Extend the CLI after the API contract stabilizes with commands such as deploy request, deploy approve, deploy cancel, deploy view, and deploy logs. Keep the operator deploy promote command from OpenAgentsInc/openagents#12 visibly separate.

Execution and provider boundary

Define a provider behavior that receives a fully admitted immutable run, never raw user authority. The provider reports typed progress and a terminal receipt. Initial providers can include:

• The existing Forge direct-load, relup, and rolling-replacement machinery for an OpenAgents-managed environment.
• A cloud rollout provider for container or VM releases.
• A preview provider for ephemeral environments.

Providers must be idempotent by run ID, redact secrets, support bounded cancellation where technically safe, and reconcile after worker restart. The control plane, not the provider, owns policy state and the terminal user-visible record.

Use a durable queue or state-driven worker model with leases, retry bounds, and reconciliation. A process crash must not lose an approval, duplicate a deployment, or misreport an uncertain provider result as success.

Environment protections

Support these policies incrementally:

• Required checks tied to the exact commit and artifact digest.
• Required human approval and separation of duties.
• Allowed branches, tags, and source workflows.
• Deployment windows and manual freeze controls.
• Per-environment concurrency with cancel, queue, or reject behavior.
• Maximum artifact age and check-result validity.
• Automatic supersession rules for preview environments; no implicit supersession for production.

Policy evaluation must produce a durable explanation that the UI, CLI, and audit API can show without revealing secrets.

Secrets and isolation

Repository workflows must never receive provider credentials directly. Resolve secrets at execution time for the bound provider and environment, expose them only to the isolated runner that needs them, and record references rather than values. Define rotation, revocation, redaction, and access-audit behavior before enabling third-party providers.

Treat workflow output, artifact metadata, and logs as untrusted tenant data. Bound sizes, sanitize rendered output, prevent cross-repository references, and apply repository visibility to every read path.

Relationship to issues and projects

Link deployment requests and terminal receipts to issues, project items, commits, workflow runs, and releases by durable IDs. A project status must not become the deployment state. Show qualification and deployment evidence on the issue timeline without changing issue closure automatically unless repository policy explicitly enables that automation.

Delivery phases

1. Publish the domain and API contract, authority matrix, threat model, and provider behavior.
2. Implement environments, deployment requests, append-only events, and a fake provider with complete state-machine tests.
3. Add protected-environment approvals, checks, scoped workflow identities, and audit export.
4. Integrate one real nonproduction provider and qualify retry, cancellation, reconciliation, and secret redaction.
5. Add CLI and UI surfaces, signed webhooks, and issue/project evidence links.
6. Enable tenant production environments only after isolation, recovery, and controlled-failure drills pass.

Tests and qualification

Prove at minimum:

• Cross-repository reads, approvals, cancellations, provider bindings, and secret references are denied.
• A workflow token cannot widen its repository, environment, commit, artifact, or run audience.
• Required checks cannot be replayed for different bytes.
• Approval separation and operator/tenant authority boundaries hold.
• Duplicate requests and worker retries do not duplicate provider execution.
• Crashes at every transition reconcile to an accurate terminal or explicitly uncertain state.
• Cancellation and supersession follow environment policy.
• Events, webhooks, CLI output, logs, and audit exports redact all credentials and secrets.
• Provider failure, timeout, and partial rollout never produce a success receipt.

Acceptance criteria

• The repository contains an approved deployment-domain contract, authority matrix, and threat model.
• A user can request and observe a deployment through the public API without receiving platform operator authority.
• A protected environment blocks until its exact checks and approvals pass.
• Durable retries and reconciliation prevent duplicate or falsely successful deployments.
• The first provider passes nonproduction controlled-failure and recovery qualification.
• Deployment evidence links cleanly to the existing issue and project system.