Oz > Managing agents

Credential strategy

Choose which principal's credentials a cloud agent run uses for Git and GitLab operations with the per-run credential_strategy field — EXECUTOR or CREATOR.

The credential_strategy field lets you control which principal’s credentials a cloud agent run uses when Warp mints tokens for Git and GitLab operations. Set it per run to decide whether operations authenticate as the run’s execution principal or as its creator — without changing who executes the run.

Key features

Per-run control - Choose the credential source for each run independently of who executes it.
Two explicit strategies - Select EXECUTOR to use the execution principal’s credentials or CREATOR to always use the run creator’s credentials.
Backward compatible default - Omitting the field preserves today’s behavior, which is identical to EXECUTOR.
GitHub and GitLab support - The same field governs credential selection for both GitHub and GitLab environments.
Fast-fail validation - When set explicitly, the platform verifies the required credential exists at task creation time, before any compute is spent.

How it works

A cloud agent run has two associated principals:

Execution principal - The identity that executes the run. This can be a user or a service account (cloud agent).
Creator - The identity that created the run. This can also be a user or a service account.

The credential_strategy field determines which of these principals supplies credentials when Warp mints user- or team-scoped tokens for the run. The credential type is always derived from the selected principal’s type:

A user principal produces the user’s personal OAuth token for the relevant code forge.
A service account principal produces a GitHub App installation token (or the equivalent team-level credential).

credential_strategy accepts one of two explicit values, or it can be left unset:

EXECUTOR - Credentials come from the run’s execution principal. This is the explicit form of the default behavior.
CREATOR - Credentials always come from the run creator, regardless of the execution principal.
(unset) - Behaves identically to EXECUTOR.

The strategy is set at run creation time and snapshotted onto the run record alongside the creator and execution_principal. It cannot be changed after the run is created, so the effective credential behavior is always recoverable from the run record.

GitHub behavior

The credential minted for GitHub operations depends on the strategy and the selected principal’s type:

EXECUTOR with a service account execution principal - A GitHub App installation token scoped to the environment’s repos is minted for the team that owns the service account. If no installation covers the repos, the run fails at task creation time.
EXECUTOR with a user execution principal - The execution principal’s personal GitHub OAuth token is used. If they have no connected GitHub account, the run fails at task creation time.
CREATOR with a user creator - The run creator’s personal GitHub OAuth token is used. If the creator has no connected GitHub account, the run fails at task creation time.
CREATOR with a service account creator - A GitHub App installation token scoped to the environment’s repos is minted for the team that owns the creator service account. If no installation covers the repos, the run fails at task creation time.

When the field is unset, behavior is identical to EXECUTOR.

GitLab behavior

GitLab environments follow the same model, with an interim limitation for service accounts:

EXECUTOR with a user execution principal - The execution principal’s personal GitLab OAuth token is used. If they have no connected GitLab account, the run fails at task creation time.
EXECUTOR with a service account execution principal - GitLab team-level credentials (the equivalent of GitHub App tokens) are not yet supported. In the interim, the run falls back to the creator’s GitLab OAuth connection when available; if the creator has no connected GitLab account, task creation is rejected.
CREATOR with a user creator - The run creator’s personal GitLab OAuth token is used.
CREATOR with a service account creator - GitLab team-level credentials for service accounts do not yet exist, so task creation is rejected until they become available.

When the field is unset, behavior is unchanged from today.

Setting the credential strategy

Set credential_strategy in the config block of the run creation request. See the Oz API & SDK reference for the full request schema and the Agents API Reference for endpoint details.

Accepted values

EXECUTOR - Source credentials from the execution principal.
CREATOR - Source credentials from the run creator.

The field is optional. Omitting it defaults to EXECUTOR behavior. Any other non-empty value is rejected with a 400 validation error before the run is created.

Create a run with a credential strategy

Build the run creation request with a config block.
Add credential_strategy to the config block, set to EXECUTOR or CREATOR.
Submit the request. The platform validates that the required credential is available before the sandbox spawns, and rejects the request with a descriptive error if it is not.

curl -X POST https://app.warp.dev/api/v1/agent/run \
  -H "Authorization: Bearer $WARP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Open a PR with the dependency updates.",
    "config": {
      "environment_id": "<ENV_ID>",
      "credential_strategy": "CREATOR"
    }
  }'

Validation

When credential_strategy is set explicitly, the platform validates the required credential at task creation time, before the sandbox spawns:

For CREATOR - The creator principal’s type determines the check. User creators must have a connected OAuth account for the relevant code forge; service account creators must have a GitHub App installation covering the environment’s repos (or, for GitLab, task creation is rejected in the interim).
For EXECUTOR - The same checks apply to the execution principal.

If validation fails, the run creation request is rejected with a descriptive error. This fast-fail prevents wasted compute and surfaces misconfigurations immediately.

When credential_strategy is unset, no additional pre-flight check runs beyond today’s existing behavior.

Cloud agents - How runs execute as users or service accounts.
Environments - The runtime context and repos a run uses.
GitLab integration - Connect cloud agents to GitLab repositories.
Oz API & SDK - Programmatic access to the run creation API.
API keys - Personal and agent API keys.