---
title: Configuration
description: Detailed configuration options for Copilot
---

# Configuration Options

Copilot provides extensive configuration options to customize your workflow. Use the tabs below to jump to the category you need.

PR bot approval uses the versioned `pullRequestApproval` setup object and `PR_APPROVAL_POLICY` Variable, not a free-form Action override. See the [guarded approval configuration reference](/pull-requests/guarded-approval) for every field, bound, and safety prerequisite.

<Tabs sync={false}>
  <Tab title="Authentication & AI" icon="key">
    ## Authentication

    - `token`: GitHub token for repository operations (required)

    ## Agent CLI selection

    - `agent-provider`: CLI runtime (`codex`, `opencode`, or `cursor`; default: `codex`)
    - `agent-model-provider`: provider serving the selected model (default: `openai`)
    - `agent-model`: model name without the provider prefix (for example `gpt-6-luna`)
    - `agent-effort`: optional reasoning effort or provider-specific model variant
    - `agent-executable`: optional exact provider executable basename or absolute path; arguments and wrappers are rejected
    - `findings-provider`, `findings-model-provider`, `findings-model`, `findings-effort`, `findings-executable`: optional findings override
    - `fixer-provider`, `fixer-model-provider`, `fixer-model`, `fixer-effort`, `fixer-executable`: optional fixer override
    - `AGENT_ALLOWED_MODEL_PROVIDERS`: optional comma-separated model-provider allowlist
    - `AGENT_ALLOWED_MODELS`: optional exact qualified-model allowlist

    See [Agent CLI configuration](/agents/cli-configuration) and [Agent CLI provisioning](/security-operations/operations/cli-provisioning).

    ## AI Features

    - `ai-pull-request-description-mode`: Select the PR body policy: `replace` owns the complete generated body, `append` preserves human text and maintains a Copilot-managed section, `preserve` never updates automatically but allows `/copilot description`, and `disabled` never changes the body. Defaults to `replace`.
    - `repository-locale`: BCP-47 target locale for repository-facing product messages (default: `en-US`). Values are validated and canonicalized for casing (`pt-br` becomes `pt-BR`); underscore forms such as `pt_BR` are invalid.
    - `issues-locale`: Optional issue-surface override. Its empty default inherits `repository-locale`; an explicit existing value remains authoritative.
    - `pull-requests-locale`: Optional pull-request-surface override. Its empty default inherits `repository-locale`; an explicit existing value remains authoritative.

    Addressed comments are interpreted in the effective surface locale with at most one agent call. Copilot never edits the human-authored source comment. When translation is needed, the useful bot response includes a collapsed, escaped copy of the interpreted request and original text. Unaddressed comments remain inert. Commands, paths, refs, URLs, identifiers, machine-readable fields, and operational logs are not localized. See [Agent CLI configuration](/agents/cli-configuration).

    Repository-aware `copilot doctor`, local command errors, Job Summaries, and Action completion errors use `repository-locale`, not the issue or pull-request overrides. Native Check names remain stable for branch protection; their human-facing title and summary use the target surface locale (issue, pull request, or repository). English is the default and atomic fallback; Spanish exact/base variants use reviewed bundled copy, while any other valid BCP-47 locale requires one complete schema-constrained catalog response from the configured planner/language agent. Error views localize impact, recovery, retained state, and retry guidance while preserving stable codes and correlation references; raw producer or provider messages are not replayed. Setup and CLI failures that occur before a repository profile is available remain in English.
    - `ai-ignore-files`: Comma-separated list of paths to ignore for AI operations (e.g. progress detection, Bugbot; not used for PR description, where the agent computes the diff in the workspace).
    - `bugbot-severity`: Minimum severity for Bugbot findings to report: `info`, `low`, `medium`, or `high` (default: `low`). Findings below this threshold are not posted on the issue or PR.
    - `bugbot-comment-limit`: Maximum number of findings to publish as individual issue comments or inline PR review comments (default: `20`). Extra findings are summarized in the PR review body or in one issue-only overflow comment. Clamped between 1 and 200.
    - `bugbot-fix-verify-commands`: Comma-separated commands to run after Bugbot autofix (e.g. `pnpm run build, pnpm test, pnpm run lint`). When a user asks to fix findings from an issue or PR comment, the configured agent applies fixes and these commands run before the action commits and pushes; if any fails, no commit is made. Default: empty (only the selected agent runtime is used). See [Features → Bugbot autofix](/features#workflow-triggered-behavior).
    - `bugbot-effort`: Review depth (`low`, `default`, `high`, or adaptive `smart`). Setup templates recommend `smart`.
    - `bugbot-dry-run`: Complete analysis with no publication, resolution, Check Run, configuration persistence, commit, or push.
    - `bugbot-review-drafts`: Include draft pull requests (default `false`).
    - `bugbot-trace-rules`: Include rule source and included/truncated/omitted status in summaries without exposing rule contents (default `false`).
    - `bugbot-suggested-changes`: Enable exact RIGHT-side line suggestions (default `true`).
    - `bugbot-telemetry`: Emit content-free review telemetry (default `true`).
    - `bugbot-fail-on-unresolved`: Fail the Action and its native Check when the final projection has `open`, `reopened`, or `verification-required` findings. Disabled by default, so those actionable states are reported neutrally; `unknown` and incomplete reconciliation always fail.
    - `bugbot-organization-rules`: Semicolon/newline-separated organization review rules.
    - `ai-members-only`: Restrict AI features to only organization/project members (default: "false"); when true, AI PR description is skipped if the PR author is not a member.
    - `ai-include-reasoning`: Include concise provider-supplied explanation metadata when available (default: `false`). It never requests or publishes hidden chain-of-thought.
  </Tab>

  <Tab title="Branches & Labels" icon="code-branch">
    ## Branch Management

    - `issue-managed-branches`: Create and verify a linked branch after `in-progress` (default: "true")
    - `pre-branch-sdd`: Require a validated SDD before implementation for eligible issues (default: "false")
    - `branch-management-emoji`: Emoji for branched issues (default: "🧑‍💻")

    ## Branch Types

    - `main-branch`: Main branch name (default: "master")
    - `development-branch`: Development branch name (default: "develop")
    - `feature-tree`: Feature branch prefix (default: "feature")
    - `bugfix-tree`: Bugfix branch prefix (default: "bugfix")
    - `hotfix-tree`: Hotfix branch prefix (default: "hotfix")
    - `release-tree`: Release branch prefix (default: "release")
    - `docs-tree`: Documentation branch prefix (default: "docs")
    - `chore-tree`: Chore branch prefix (default: "chore")

    ## Issue Labels

    - `feature-label`: Feature branch label (default: "feature")
    - `bugfix-label`: Bugfix branch label (default: "bugfix")
    - `hotfix-label`: Hotfix branch label (default: "hotfix")
    - `release-label`: Release branch label (default: "release")
    - `docs-label`: Documentation label (default: "docs")
    - `documentation-label`: Alternative documentation label (default: "documentation")
    - `chore-label`: Chore label (default: "chore")
    - `maintenance-label`: Maintenance label (default: "maintenance")
    - `bug-label`: Bug type label (default: "bug")
    - `enhancement-label`: Enhancement type label (default: "enhancement")
    - `question-label`: Question label (default: "question")
    - `help-label`: Help request label (default: "help")
    - `deploy-label`: Deploy action label (default: "deploy")
    - `deployed-label`: Deployed status label (default: "deployed")
    - `priority-high-label` through `priority-none-label`: Priority labels (default: "priority: high", etc.)

    ## Size Labels and Thresholds

    **Size labels:** `size-xxl-label`, `size-xl-label`, `size-l-label`, `size-m-label`, `size-s-label`, `size-xs-label` (defaults: "size: XXL", etc.)

    **Thresholds** (each size has three): `size-{size}-threshold-lines`, `size-{size}-threshold-files`, `size-{size}-threshold-commits`

    Default thresholds: XXL 1000/20/10, XL 500/10/5, L 250/5/3, M 100/3/2, S 50/2/1, XS 25/1/1 (lines/files/commits).
  </Tab>

  <Tab title="Project & Behavior" icon="table-cells-large">
    ## Project Integration

    - `project-ids`: Comma-separated list of GitHub Project IDs to link issues and PRs
    - `project-column-issue-created`: Project column for new issues (default: "Todo")
    - `project-column-pull-request-created`: Project column for new PRs (default: "In Progress")
    - `project-column-issue-in-progress`: Project column for in-progress issues (default: "In Progress")
    - `project-column-pull-request-in-progress`: Project column for in-progress PRs (default: "In Progress")
    - `desired-assignees-count`: Number of assignees for issues/PRs (default: 1, max: 10)
    - `desired-reviewers-count`: Number of reviewers for PRs (default: 1, max: 15)

    ## Customization

    - `emoji-labeled-title`: Enable emoji titles based on labels (default: "true")
    - `commit-prefix-transforms`: Comma-separated list of transforms for commit prefix from branch name (e.g. "replace-slash", "kebab-case"). See README for full list.
    - `reopen-issue-on-push`: Reopen closed issues on new commits (default: "true")
    - `inactivity-threshold-hours`: Hours without activity before a waiting issue is closed by the scheduled cleanup (default: 168; valid range: 1–8760)

    ## Workflow Files

    - `release-workflow`: Release workflow filename (default: "release_workflow.yml")
    - `hotfix-workflow`: Hotfix workflow filename (default: "hotfix_workflow.yml")

    ## Deployment orchestration

    - `release-reconciliation-strategy`: `production-lineage` (default), `canonical-gitflow`, or `manual`
    - `hotfix-reconciliation-strategy`: `production-lineage` (default), `canonical-gitflow`, or `manual`
    - `reconciliation-pr-mode`: `auto` (default), `auto-merge`, `merge-queue`, or `create-only`
    - `merge-queue-check-attestations`: JSON array of exact `(context, integrationId, targets)` attestations for otherwise-unverifiable required checks (default: `[]`; max 50 entries and 16 KiB)
    - `reconciliation-backmerge-mode`: `auto` (default), `direct`, or `sync-branch`
    - `hotfix-active-release-policy`: `prefer-release` (default), `development`, or `both`
    - `reconciliation-tree`: Safe ephemeral branch prefix (default: `sync`)
    - `reconciliation-cleanup`: `all` (default), `source-only`, `sync-only`, or `none`
    - `reconciliation-issue-completion`: `close` (default) or `keep-open`
    - `orchestration-presentation-mode`: `guided` (default), `compact`, or `quiet`
    - `orchestration-diagrams`: Show a fixed Mermaid diagram and textual equivalent (default: `true`)
    - `orchestration-comment-mode`: `update` (default) or `milestones`

    See [Release and hotfix orchestration](/issues/deployment-orchestration)
    before changing these coordinated safety settings.

    Queue readiness is live repository policy, not a snapshotted deployment
    preference. Copilot combines classic branch protection and every effective
    ruleset for the exact target, verifies accessible GitHub Actions workflow
    contracts on the target and candidate refs, and fails closed before PR
    creation and again before enqueue. An attestation can authorize only an
    `unknown` check with the exact identity and logical target; it never
    overrides a workflow proven to lack `merge_group: checks_requested`.
  </Tab>

  <Tab title="Single Actions" icon="play">
    ## Single Actions

    - `single-action`: Single action to run (e.g. `check_progress_action` or `think_action`). See [Single Actions](/single-actions).
    - `single-action-issue`: Issue number for actions that require one (for example `check_progress_action` and workflow-owned deployment actions)
    - `single-action-version`: Version for `create_release`, or the version bound to the durable deployment operation used by workflow-owned `create_tag`
    - `single-action-title`: Durable release/hotfix title used by `prepare_deployment_action`
    - `single-action-changelog`: Durable release/hotfix changelog used by `prepare_deployment_action`
    - `single-action-message`: Markdown body for `publish_issue_comment`
    - `single-action-comment-id`: Optional existing comment ID for `publish_issue_comment`
    - `single-action-comment-mode`: `create`, `replace`, or `append`; defaults to `create` without an ID and `replace` with an ID
    - `inactivity-threshold-hours`: Inactivity window for `close_inactive_issues_action` (default: `168` hours; valid range: `1`–`8760`)

  </Tab>
</Tabs>

## GitHub Actions resource scope

`copilot setup` treats Secrets and Variables as two independent resource classes. Each class can default to the repository or the organization, and individual names can override that default. Organization resources use GitHub's `selected`, `private`, or `all` visibility; `selected` is the recommended least-privilege choice.

```yaml
manageRepositorySecrets: true
manageRepositoryVariables: true
storage:
  secrets:
    defaultScope: organization
    organizationVisibility: selected
    preserveExisting: true
  variables:
    defaultScope: repository
    preserveExisting: true
    overrides:
      OPENAI_API_KEY: organization
```

The immutable questionnaire first inspects the repository and reports repository-scoped resources, organization resources available to that repository, repository visibility, and access errors. It then asks separately about Secret and Variable storage. Each accepted answer creates a fresh configuration snapshot; defaults, overrides, prior answers, and the result do not share mutable nested references. Repository resources take precedence over organization resources. With `preserveExisting: true`, an effective organization resource is inherited instead of being shadowed by a new repository value; add a name under `storage.secrets.overrides` or `storage.variables.overrides` when a repository-specific value is intentional.

Organization storage is available only for organization-owned repositories and requires organization Actions permissions on the setup PAT. If only one class should be global, set that class to `organization` and leave the other at `repository`. `--skip-secrets` and `--skip-variables` disable their respective setup operations without changing the other class.

`--non-interactive` constructs no terminal and resolves only defaults, config,
flags, and explicit external inputs. `--yes` approves the final plan but never
invents a missing token, credential, target, or storage prerequisite. There is
also a separate `--confirm-unverifiable-write-permissions` acknowledgement for
unattended runs where identity and required reads are verified or positively
operationally usable but safe probes cannot prove required writes. It never
bypasses missing or unusable unverifiable read access. There is no legacy configuration shape or compatibility alias: unknown keys and removed
values fail validation.

## Complete input reference

The tables above group the most commonly changed inputs. The following inputs are
also part of the public `action.yml` contract and are easy to miss when copying a
workflow. Defaults below are the action defaults; values supplied by `copilot setup`
may be forwarded through Repository Variables instead.

### Operational and single-action inputs

| Input | Default | Description |
| --- | --- | --- |
| `debug` | `false` | Enable verbose diagnostic logging. Do not enable it when credential-bearing values could be exposed by surrounding steps. |
| `single-action` | empty | Run one explicit action instead of the event-driven pipeline. |
| `single-action-issue` | empty | Issue number for a single action that operates on an issue. |
| `single-action-version` | empty | Version used by release and tag single actions. |
| `single-action-title` | empty | Title snapshotted by `prepare_deployment_action`. |
| `single-action-changelog` | empty | Markdown changelog snapshotted by `prepare_deployment_action`. |
| `single-action-message` | empty | Markdown body published by `publish_issue_comment`. |
| `single-action-operation-id` | empty | Internal durable deployment identity. Continuation workflows must pass the exact ID parsed or dispatched by Copilot; do not set it for ordinary actions. |
| `single-action-comment-id` | empty | Existing issue comment ID to replace or append to. |
| `single-action-comment-mode` | empty | `create`, `replace`, or `append`; inferred from whether a comment ID is present when omitted. |
| `inactivity-threshold-hours` | `168` | Hours without activity before the scheduled action closes an eligible waiting issue. |
### Task-specific agent overrides

The common `agent-*` inputs define the baseline runtime/model tuple. `findings-*`
and `fixer-*` override that tuple for Bugbot analysis and autofix. The other roles
are optional overrides: when at least one role-specific value is supplied, that
role gets its own validated configuration; otherwise it inherits the common tuple.

| Role | Provider | Model provider | Model | Effort | Executable |
| --- | --- | --- | --- | --- | --- |
| Planner | `planner-provider` | `planner-model-provider` | `planner-model` | `planner-effort` | `planner-executable` |
| Findings | `findings-provider` | `findings-model-provider` | `findings-model` | `findings-effort` | `findings-executable` |
| Reviewer | `reviewer-provider` | `reviewer-model-provider` | `reviewer-model` | `reviewer-effort` | `reviewer-executable` |
| Fixer | `fixer-provider` | `fixer-model-provider` | `fixer-model` | `fixer-effort` | `fixer-executable` |
| Tester | `tester-provider` | `tester-model-provider` | `tester-model` | `tester-effort` | `tester-executable` |

`copilot setup` can configure the provider, model provider, model, and effort for
these six roles independently. The setup workflow templates also accept the
corresponding `*_EXECUTABLE` variables. They select only the expected executable;
Copilot always reconstructs the complete provider arguments and policy.

### Lifecycle labels

These inputs configure the labels synchronized by issue, pull request, and agent
activity flows. The durable lifecycle phase is exclusive; the temporary activity
and waiting dimensions can coexist with it.

| Input | Default | Meaning |
| --- | --- | --- |
| `state-planned-label` | `state:planned` | A plan is available. |
| `state-specifying-label` | `state:specifying` | A required SDD is being clarified or revised. |
| `state-working-label` | `state:working` | Implementation may proceed. |
| `state-reviewing-label` | `state:reviewing` | A pull request is under review. |
| `state-changes-requested-label` | `state:changes-requested` | Review findings require changes. |
| `state-verified-label` | `state:verified` | The pull request was merged successfully. |
| `state-ready-label` | `state:ready` | The latest result is ready for human action. |
| `state-blocked-label` | `state:blocked` | Human intervention is required. |
| `state-ai-processing-label` | `state:ai-processing` | Temporary marker while an agent is analyzing or working; removed at run end. |
| `state-awaiting-maintainer-label` | `state:awaiting-maintainer` | Waiting for a maintainer response, approval, or merge. |
| `state-awaiting-issue-author-label` | `state:awaiting-issue-author` | Waiting for information or changes from the issue author. |

### Issue type inputs

`copilot setup` uses these inputs when creating or updating organization Issue
Types. Each type has a configurable name, description, and color.

| Type | Name | Description | Color | Defaults (name / color) |
| --- | --- | --- | --- | --- |
| Task | `issue-type-task` | `issue-type-task-description` | `issue-type-task-color` | `Task` / `blue` |
| Bug | `issue-type-bug` | `issue-type-bug-description` | `issue-type-bug-color` | `Bug` / `orange` |
| Feature | `issue-type-feature` | `issue-type-feature-description` | `issue-type-feature-color` | `Feature` / `green` |
| Documentation | `issue-type-documentation` | `issue-type-documentation-description` | `issue-type-documentation-color` | `Documentation` / `pink` |
| Maintenance | `issue-type-maintenance` | `issue-type-maintenance-description` | `issue-type-maintenance-color` | `Maintenance` / `purple` |
| Hotfix | `issue-type-hotfix` | `issue-type-hotfix-description` | `issue-type-hotfix-color` | `Hotfix` / `red` |
| Release | `issue-type-release` | `issue-type-release-description` | `issue-type-release-color` | `Release` / `yellow` |
| Question | `issue-type-question` | `issue-type-question-description` | `issue-type-question-color` | `Question` / `gray` |
| Help | `issue-type-help` | `issue-type-help-description` | `issue-type-help-color` | `Help` / `purple` |

## Persistence and current-schema state

Copilot persists certain configuration fields directly in the **GitHub Issue description** as a hidden JSON block. This allows the action to "remember" state across different runs and across issues/PRs.

### Persistence strategy

When updating the configuration (for example, after a push or label change), Copilot uses one strict contract:

1. **Current state**: the action computes the latest supported branch and orchestration state.
2. **Schema check**: stored state is accepted only when `schemaVersion` is the current version (`3`). A different or missing version is not migrated or inferred.
3. **Known-field merge**: when a current event has no replacement for a known durable field, the value from valid current-schema state is retained. Unknown keys are discarded.
4. **Transient exclusion**: `results` is never persisted, which prevents result payloads from accumulating in the issue description.

The hidden block is owned by Copilot. Do not add third-party or manually managed keys to it; they are outside the contract and will be removed on the next write.

### Persistence failures

If GitHub cannot read or update the issue description, the run fails closed after
reporting the persistence error. Copilot does not treat a failed write as a
successful run: the recommendation state is therefore not considered
committed, so a later retry cannot silently rely on stale state. Runs that do
not have an issue target simply skip this persistence step.