---
title: Features & Capabilities
description: Complete reference of what the Copilot GitHub Action does
---
# Features & Capabilities
This page describes **every function** the Copilot GitHub Action provides: workflow-triggered behavior (issues, pull requests, pushes) and **single actions** you can run on demand.
When you open, edit, or label issues: branch creation, project linking, assignees, issue type, size labels, and comments.
When PRs are opened or updated: link to issue, project column, reviewers, AI description, size/progress sync.
On every push: commit notifications on the issue, prefix check, reopen option, size & progress labels (with the configured agent runtime). Details below.
---
## Workflow-triggered behavior
The action is typically invoked by three workflow triggers. What it does depends on the event.
### 1. Issue events (`on: issues`)
When the workflow runs on `issues` (opened, edited, labeled, unlabeled, etc.):
| Feature | Description |
|--------|-------------|
| **Branch creation** | Creates feature, bugfix, docs, chore, and release branches from the configured development line. A release records the exact development SHA at the cut; a hotfix instead starts from the commit behind the selected production version tag. Adding `in-progress` starts admitted work. When issue-managed branches are enabled, `branched` is added after the exact linked branch is verified; an optional SDD gate publishes the contract first. |
| **Branch–issue linking** | Links the new branch to the issue. The branch and native issue metadata are the visible evidence; routine linkage does not add a recap comment. |
| **Project linking** | Adds the issue to the configured GitHub Projects (by `project-ids`) and moves it to the configured column (e.g. "Todo", "In Progress"). |
| **Assignees** | Assigns up to `desired-assignees-count` members to the issue (creator preferred if in org). |
| **Issue type** | Sets the GitHub issue type (Task, Bug, Feature, Documentation, etc.) from labels. |
| **Emoji titles** | Optionally adds emojis to issue titles based on labels (`emoji-labeled-title`). |
| **Size labels** | Assigns size labels (XS–XXL) and checks size thresholds (lines, files, commits) for prioritization. |
| **Planning guidance** | When planning is requested, maintains one bounded card with 3–8 ordered steps, at most 2 short details per step, and a verifiable acceptance criterion. Copilot owns the layout; the issue locale defaults to English. Equivalent reruns are silent, while a material issue edit updates the same card. The Job Summary keeps only compact operator state. |
| **Lifecycle labels** | Maintains an exclusive durable `state:*` phase, an optional `state:ai-processing` activity marker, and an optional human-waiting label. Activity can coexist with the durable phase and is removed when the agent run finishes. |
### 2. Pull request events (`on: pull_request`)
When the workflow runs on `pull_request` (`opened`, `reopened`, `synchronize`,
or `closed`):
| Feature | Description |
|--------|-------------|
| **PR–issue linking** | Links the pull request to a distinct issue associated with its branch and relies on GitHub's native linked-PR UI. An unlinked PR still receives PR-native enrichment and is never linked to itself. |
| **Project linking** | Adds the PR to the configured GitHub Projects and moves it to the configured column. |
| **Reviewers** | Assigns up to `desired-reviewers-count` reviewers. |
| **Priority & size** | Applies priority and size checks (labels and thresholds). |
| **AI PR description** | When `ai-pull-request-description-mode` is `replace`, `append`, or `preserve`, the selected agent CLI writes a concise outcome and material changes from the optional issue context and branch diff. Validation appears only when supported by evidence; `disabled` turns the feature off. See [Pull Requests → AI-generated PR description](/pull-requests/ai-description). |
| **Conversation UX** | Publishes only purpose-specific replies and durable status cards. Equivalent retries are silent; exact bot-owned duplicates caused by concurrent runs are removed, with a short localized pointer retained only when GitHub forbids deletion. It does not add a generic action recap or decorative image. |
| **Bugbot review** | Reviews the full PR on open/reopen and the new commit range on synchronize; publishes historical review snapshots and stable line findings, then reconciles native threads, review status blocks, one current PR card, and the Check from a provider-verified projection. |
| **Guarded PR approval** | An optional separate observer may submit one native bot approval for a verified human PR revision after exact CI, coverage, Bugbot, native-review, and stale-branch-rule checks. Missing policy stays off; it never merges or substitutes human/code-owner review. See [guarded approval](/pull-requests/guarded-approval). |
### 3. Push events (`on: push`)
When the workflow runs on `push` (e.g. to any branch):
| Feature | Description |
|--------|-------------|
| **Push handling** | Treats the push as an internal signal. It does not post a per-commit summary; when configured, it can reopen the linked issue through GitHub's native state transition. |
| **Commit prefix check** | Warns if commit messages do not follow the prefix derived from the branch name (using `commit-prefix-transforms`). |
| **Reopen issue** | If `reopen-issue-on-push` is true, reopens the issue when new commits are pushed to its branch. |
| **Size & progress** | Computes size (XS–XXL) and progress (0–100%) from the branch diff; updates the **issue** and any **open PRs** for that branch with the same labels. Uses the configured agent runtime. No separate workflow is needed. |
| **Bugbot (potential problems)** | The configured agent analyzes the branch vs base and reports findings as **issue comments** when there is no PR, or as one summarized review with inline findings when a PR is available; it updates stored findings and **marks PR review threads as resolved** when applicable. Configurable via `bugbot-severity` and `ai-ignore-files`. See [Bugbot](/bugbot), [issue findings](/bugbot/detection#on-the-issue-when-no-pr-is-available), and [pull-request findings](/bugbot/detection#on-the-pull-request). |
| **Finding reconciliation** | Carries stable finding fingerprints across pushes and projects open, reopened, fixed, obsolete, dismissed, verification-required, or unknown without creating duplicate status comments. |
| **Branch drift observer** | A separate lightweight workflow watches pushes on every branch, resolves open issue/PR branch relationships, and maintains one synchronization notice when a child is behind. It does not load Bugbot or an agent. See [Branch synchronization](/issues/branch-synchronization). |
---
### 4. Scheduled inactivity cleanup (`on: schedule`)
The optional `copilot_close_inactive_issues.yml` workflow runs every six hours
and invokes `close_inactive_issues_action`. It closes only open issues with
`state:awaiting-maintainer` or `state:awaiting-issue-author` whose GitHub
`updated_at` is older than `inactivity-threshold-hours` (168 hours by default).
Pull requests, issues marked `state:ai-processing`, and candidates that become
active while the scan is running are skipped. Setup keeps this feature disabled
by default because it changes issue state; enable `inactiveIssueClosure` after
reviewing the threshold and the workflow PAT permissions.
## Single actions
When you set `single-action` (and the inputs required by that action), Copilot runs **only** that action and skips the normal issue/PR/push pipelines.
| Single action value | Inputs required | Description |
|--------------------|----------------|-------------|
| **`check_progress_action`** | `single-action-issue` | Runs progress check on demand (e.g. without pushing). Progress is normally updated automatically on every push; use this to re-run the check or when no push workflow is configured. |
| **`detect_potential_problems_action`** | `single-action-issue` | Bugbot: the configured agent analyzes the branch vs base; reports findings on the issue when no PR exists, or in one summarized PR review when one is available; updates stored findings and resolves PR threads when findings are fixed. |
| **`recommend_steps_action`** | `single-action-issue` | Uses the configured agent to recommend implementation steps from the issue description; creates or updates one plan card on the issue. |
| **`think_action`** | — | Uses the configured agent for deep code analysis and change proposals (reasoning over the codebase). No issue required. |
| **`initial_setup`** | — | Performs initial setup: creates labels, issue types, verifies access. If the repo has no version tags, creates default tag `v1.0.0` so release/hotfix issues get a base version. No issue required. |
| **`create_release`** | Internal: issue, operation ID, version | Creates or verifies the GitHub Release and its exact durable operation/SHA receipt. Supplied workflows only. |
| **`create_tag`** | `single-action-version`, `single-action-issue`, and `single-action-operation-id` | Creates or verifies immutable `v` at the accepted production SHA of the matching durable deployment operation. |
| **`publish_github_action`** | Internal: issue, operation ID, version | Updates the major Action tag/release alias from the verified version tag. This repository's supplied workflow only. |
| **`close_inactive_issues_action`** | `inactivity-threshold-hours` (optional) | Scans waiting issues and closes those inactive for the configured threshold; no issue number is required. |
| **`publish_issue_comment`** | `single-action-issue`, `single-action-message`; optionally `single-action-comment-id` and `single-action-comment-mode` | Creates a Markdown comment, or replaces/appends to a specific comment on the issue. |
| **`check_branch_sync_action`** | — | Internal lightweight push observer used by `copilot_branch_sync.yml`; compares related parent/working branches and updates the issue notice without an agent. |
| **`prepare_deployment_action`** | Internal: issue, version, title, changelog | Creates/resumes durable deployment state and opens the promotion PR. Supplied workflows only. |
| **`continue_deployment_action`** | Internal: issue, operation ID | Verifies a managed closed PR and advances the operation. Supplied continuation workflow only. |
| **`published_deployment_action`** | Internal: issue, operation ID, version | Records verified publication and creates configured reconciliation PRs. Supplied workflows only. |
| **`failed_deployment_action`** | Internal: issue, operation ID, version/message | Persists a retryable publication failure without discarding completed facts. Supplied workflows only. |
Single actions that **throw an error** if the last step fails include the seven
workflow-owned deployment/publication actions: `create_tag`, `create_release`,
`publish_github_action`, `prepare_deployment_action`,
`continue_deployment_action`, `published_deployment_action`, and
`failed_deployment_action`. They must not be invoked manually.
---
## AI features and runtime coverage
All AI features use the configured agent CLI and explicit model contract. The runtime is selected with `agent-provider`; the model provider and model are selected with `agent-model-provider` and `agent-model`. See [Agent CLI configuration](/agents/cli-configuration).
Codex is the default runtime for the repository's AI feature paths. OpenCode and Cursor are supported alternatives with deterministic adapter, policy, and failure-path coverage. Each deployment must still run an explicitly authorized authenticated smoke test for the chosen runtime, model, account, and runner image.
| Runtime | Status | Documentation |
| --- | --- | --- |
| Codex with OpenAI | Default CLI path; verify authentication and model entitlement before production use | [Codex and OpenAI](/agents/codex-openai) |
| OpenCode | Supported validated alternative | [OpenCode runtime](/agents/opencode) |
| Cursor | Supported; per-environment authenticated smoke test required | [Cursor runtime](/agents/cursor) |
| Feature | Where it runs | Description |
|--------|----------------|-------------|
| **Check progress** | Push (commit) pipeline; optional single action `check_progress_action` / CLI `check-progress` | Compares issue vs branch diff, updates progress labels, and reconciles one issue progress card only when its semantic projection changes and the analyzed branch `HEAD` is still current. Stale results change nothing and are explained in the Job Summary. It does not post per-commit narration. |
| **Bugbot (potential problems)** | Push (commit) pipeline; optional single action `detect_potential_problems_action` / CLI `detect-potential-problems` | Analyzes branch vs base and posts bounded findings near code plus one concise aggregate status card. A clean full-coverage card omits empty tables and technical detail; incomplete coverage names an effective recovery action instead of requesting identical rechecks. |
| **Do user request** | Issue comment; PR review comment | When you comment asking to perform a change in the repo (or use `/copilot implement `), the configured agent applies the changes in the workspace, runs verify commands, and the action commits and pushes with a generic message. Organization repositories require an org member; personal repositories require the owner or a `push`/`maintain`/`admin` collaborator. Uses the same `bugbot-fix-verify-commands` and agent CLI setup. |
| **Think / reasoning** | Issue/PR comment pipeline; single action `think_action` | Deep code analysis and change proposals (configured agent CLI). On GitHub, returns one sanitized, correlated semantic answer to an explicit `/copilot` command or exact bot mention; Think itself has no comment mutation capability. In the CLI, it prints the answer locally and `--issue` is optional context. |
| **Explicit Copilot commands** | Issue and PR comments | `/copilot help`, `/copilot plan`, `/copilot clarify`, `/copilot estimate`, `/copilot test-plan`, `/copilot explain`, `/copilot diagnose`, `/copilot analyze`, `/copilot status`, `/copilot review`, `/copilot findings`, `/copilot recheck`, `/copilot fix`, `/copilot dismiss`, `/copilot remember`, `/copilot implement`, and `/copilot sync-branch` provide a bounded, predictable interface. |
| **Branch synchronization** | All-branch push observer; issue/PR command | Detection is agent-free. An authorized command merges parent into working branch, invokes the fixer only for eligible Git conflicts, validates the prepared merge, runs configured checks, revalidates remote heads, pushes, and reports the outcome. |
| **Repository language and request adaptation** | Generated GitHub UI; addressed issue/PR comments; repository-aware CLI | Uses `repository-locale` (`en-US` by default), with optional inheriting `issues-locale` and `pull-requests-locale` overrides. An addressed foreign-language request is safely interpreted once; its source comment is never edited, and translation context appears only with the useful bot response. Job Summary, Action completion, deployment, doctor, and local error recovery use complete locale catalogs while codes and references remain stable. Unaddressed human and automated comments are inert. |
| **AI PR description** | Pull request pipeline | Uses `.github/pull_request_template.md` as guidance to write a concise body from optional issue context and the branch diff (configured agent CLI). |
| **Copilot** | CLI `copilot do` | Code analysis and file edits via the configured agent runtime. |
| **Recommend steps** | Single action / CLI | Suggests implementation steps from the issue description (configured agent CLI). |
## GitHub conversation UX
Copilot treats issue comments, PR comments, reviews, and durable dashboards as
product UI. New normal issues receive one implementation-plan card; later edits
update that card. Pushes may update one progress card. Branch drift, Bugbot, and
release/hotfix orchestration each own one stateful card. Explicit commands and
mentions receive at most one correlated reply.
Routine labels, assignees, project moves, title normalization, PR linkage,
description refreshes, pushes, reopens, merges, and closes do not create a
generic roll-up. The Job Summary keeps aggregate result counts and expands only
safe error recovery evidence; internal result names, step narration, and arbitrary
error text remain in logs.
Progress is guarded twice against branch movement: before native label writes
and before every progress-card mutation. This also applies to the on-demand
Action and repository-aware CLI because both snapshot the authoritative remote
branch before analysis.
Hidden markers provide stable identity and are trusted only when the comment is
authored by the configured bot. Generated conversation surfaces do not include
decorative media or expose configuration for it.
---
## Workflow concurrency and sequential execution
**Two coordination policies:** durable mutation workflows preserve every admitted event in a workflow-local queue. Commit and Pull Request each have a separate repository/branch latest-revision lane, so paired events cannot cancel one another.
GitHub's native [concurrency](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency) can cancel in-progress runs when a newer one starts and can retain only one pending run. The replaceable branch jobs therefore use event-specific keys: Commit uses `copilot-push-${{ github.repository }}-${{ github.ref_name }}`; Pull Request code/lifecycle analysis uses the branch key with an `analysis` suffix; and the dedicated review-state workflow uses the same branch key with a `review-state` suffix. Each lane cancels only its own obsolete revision. Commit still synchronizes issue progress, then Bugbot performs a read-only exact-head lookup because a `push` payload does not contain PR identity. A validated open same-repository PR makes the push stop before review-context loading or agent invocation; the PR `synchronize` event exclusively owns review for that head. This prevents duplicate reviews without letting a push or review-state event cancel useful PR analysis. Branches without an open PR retain push-time Bugbot. Metadata-only `pull_request: edited` events are not subscribed because Copilot changes the PR body itself; excluding them prevents self-generated run cascades and preserves human metadata edits. Application-level head guards prevent an older run from updating a newer PR, and the next code/lifecycle run repairs any durable half-transition discovered after cancellation. Fixed workflow/job names expose analysis and review-state checks without leaking an unevaluated expression when GitHub skips bot-authored events. A separate merge-group workflow avoids a skipped duplicate on normal PRs while deliberately preserving the exact `Copilot - Pull Request` required-check context for branch-protection compatibility.
For non-replaceable issue and comment mutations, Copilot adds an application-level queue per workflow: every started run waits for earlier active runs of that same workflow, so intermediate events are not discarded by a native concurrency group. Runs triggered by the PAT owner that would only re-trigger the normal pipeline complete before entering this queue.
Release and hotfix workflows instead use one native, issue-scoped deployment mutex:
`copilot-deployment-${{ github.repository_id }}-${{ inputs.issue }}` with
`cancel-in-progress: false` and `queue: max`. A permissionless validation job runs
first and every write-capable job is its transitive descendant. Managed pull-request
continuations resolve and verify the durable operation using read-only permissions,
then enter that same issue-scoped mutex before obtaining mutation permissions. There
is no alternate queue-only Action mode or direct/local deployment mutation path.
### How it works
1. For a GitHub Action run with a PAT, the action first compares the event actor with the authenticated PAT user. A normal run from the same account completes successfully before project composition, agent provisioning, setup, or queue polling. A valid explicit single action continues through the normal lifecycle.
2. An admitted run resolves the current workflow file from `GITHUB_WORKFLOW_REF` and queries the workflow-scoped endpoint concurrently for `in_progress`, `queued`, `requested`, `waiting`, and `pending` runs with `per_page: 100`. It then keeps only runs with a **lower run ID** (i.e. started earlier). Completed history and unrelated workflows are never included.
3. Provider failures fail closed. Transient 408/5xx/network errors use bounded exponential retry; HTTP 429 and rate-limited 403 responses honor `Retry-After` or `x-ratelimit-reset`, then use a slower bounded fallback. Diagnostics contain only the retry reason, attempt, delay, and safe reset timestamp metadata.
4. If any such run exists, the action polls immediately and then uses adaptive 5s, 10s, 20s, 40s, and 60s maximum delays with bounded ±20% jitter. The absolute queue wait is limited to 90 minutes.
5. When no earlier active run in the mutation queue remains, the action continues. A provider failure or queue deadline never becomes an empty result, so setup and mutation work cannot proceed with an unknown queue state.
The queue deliberately traverses every page in each active-status subset because
exact counting must detect a matching run on a later page. Querying only active
states keeps each poll proportional to the live queue, and `per_page: 100` minimizes
the remaining API calls while preserving correctness.
So you get a **workflow-local mutation queue** for durable events, plus
**event-specific latest-revision lanes** for Commit and Pull Request. Open PRs
have one Bugbot owner, and unrelated branches and workflows do not block each
other.
### Example
```yaml
name: Copilot - Issue
on:
issues:
types: [opened, edited, labeled, unlabeled]
jobs:
copilot-issues:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
with:
persist-credentials: false
- uses: vypdev/copilot@v3
with:
token: ${{ secrets.PAT }}
project-ids: '2,3'
```
Durable mutation workflows deliberately do not use a GitHub Actions `concurrency` block: native cancellation retains only one pending run and can discard intermediate issue, comment, or release mutations. The Commit and Pull Request templates are the deliberate exception for their own replaceable branch revisions, but they use distinct groups and cannot cancel one another. Native concurrency also remains appropriate for replaceable read-only workflows such as CI and RepoWise.
---
## Other capabilities
- **Commit prefix transforms**: `commit-prefix-transforms` defines how branch names are turned into commit prefixes (e.g. `replace-slash`, `kebab-case`). Used for validation and comments.
- **Issue types**: Configurable issue type names, descriptions, and colors (Task, Bug, Feature, Documentation, Maintenance, Hotfix, Release, Question, Help).
- **Debug**: Set `debug: true` for verbose logging.
For full input reference, see [Configuration](/configuration).