docs: credential strategy for agent runs (REMOTE-1815) [auto-draft]

[rachaelrenk]

Summary

Auto-drafted documentation for Configurable credential strategy for agent runs.

• Feature: Credential strategy (credential_strategy) for cloud agent runs
• Spec ID: REMOTE-1815
• Spec PR: https://github.com/warpdotdev/warp-server/pull/12156

This adds a per-run credential_strategy field (EXECUTOR vs CREATOR, default EXECUTOR) that controls which principal's credentials Warp mints for Git/GitLab operations in a cloud agent run. New page: src/content/docs/platform/credential-strategy.mdx, plus a placeholder sidebar entry in src/sidebar.ts.

This draft was generated in ambient mode (triggered by scan-new-specs). Content is derived only from PRODUCT.md and codebase-verified facts — no TECH.md-derived content was included.

Docs outline (auto-generated)

The following outline was generated from the spec. @captainsafia: please review and check off each item, or leave a comment with corrections.

Content structure

• H1: Credential strategy
• Opening paragraph describes: what credential_strategy controls (which principal's credentials are used for Git/GitLab operations, set per run)
• Key features section covers: per-run control, two explicit strategies, backward-compatible default, GitHub + GitLab support, fast-fail validation
• How it works section covers: execution principal vs creator, how principal type maps to credential type, EXECUTOR/CREATOR/unset semantics, snapshotting onto the run record
• ## GitHub behavior: per-strategy behavior for user vs service account principals
• ## GitLab behavior: per-strategy behavior including the service-account interim limitation
• ## Setting the credential strategy with steps: build request → add credential_strategy to config block → submit; plus accepted values, curl example, and validation subsection
• Related pages: Cloud agents, Environments, GitLab integration, Oz API & SDK, API keys

Items needing engineer verification ⚠️

• Endpoint path — The public docs document run creation as POST /agent/run; PRODUCT.md §15 references POST /api/v1/agent/runs. Confirm the exact endpoint and that credential_strategy lives in the request's config block.
• GET response — Confirm credential_strategy is returned in run GET responses (PRODUCT.md §15) and is present in the public OpenAPI spec that powers the /api reference. It is not yet in the docs repo's synced developers/agent-api-openapi.yaml, so the Scalar /api reference will not show it until sync-openapi-spec runs.
• Release/availability — Confirm whether this field is generally available or gated behind a feature flag / plan, so the page can note any gating.
• UI surface / screenshot — Confirm whether the effective credential strategy is surfaced anywhere in the Oz web app (e.g. run detail). A [TODO: docs reviewer — screenshot needed] placeholder is left in the page; computer use was unavailable, so no screenshot was captured.
• Sidebar placement — Placed under Oz → Managing agents in src/sidebar.ts with a // [TODO: docs reviewer — confirm placement] note. Confirm this is the right home (vs. Reference → API & SDK).

Verified from codebase ✅

• Field name config.credential_strategy — confirmed via the validation error string in router/handlers/public_api/agent_webhooks.go (config.credential_strategy %q is not valid; accepted values are %q and %q).
• Accepted values CREATOR and EXECUTOR — confirmed in model/types/enums/credential_strategy.go and related code.
• 400 validation for any other non-empty value — consistent with the webhook validation error and PRODUCT.md §16.
• Pre-flight validation at task creation time (before sandbox spawn) — confirmed in logic/ai/ambient_agents/credential_strategy_validation.go.
• Git token resolution respects the strategy — confirmed in logic/ai/ambient_agents/git_credentials.go.

Full list of [UNVERIFIED] / [TODO] items in the draft

• credential-strategy.mdx (How it works): [TODO: docs reviewer — screenshot needed] + [UNVERIFIED] whether effective strategy shows in the Oz web app UI.
• credential-strategy.mdx (Setting the credential strategy): [TODO: engineer to verify] exact endpoint (POST /agent/run vs POST /api/v1/agent/runs) and config block placement.
• credential-strategy.mdx (Setting the credential strategy): [TODO: engineer to verify] credential_strategy returned in GET responses and present in the public OpenAPI spec.
• src/sidebar.ts: // [TODO: docs reviewer — confirm placement].

/cc @captainsafia

Requesting review from @rachaelrenk and @hongyi-chen.

Conversation: https://app.warp.dev/conversation/e8fd611f-bdd4-40ea-af4f-0efa6ccfb970
Run: https://oz.warp.dev/runs/019fae9f-b516-7887-b592-fa53ff7a5e95

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 29, 2026 4:13pm

[captainsafia]

Heads up, @rachaelrenk! This is part of some on-going work that I am doing around making it easier to configure run attribution. I think we can hold off on iterating on this until that work is done then do an exhaustive docs page on credential strategies/what principals are used where/how to configure it/etc.