---
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.

<CardGroup cols={3}>
  <Card title="Issue events" icon="circle-dot" href="/issues">
    When you open, edit, or label issues: branch creation, project linking, assignees, issue type, size labels, and comments.
  </Card>
  <Card title="Pull request events" icon="code-pull-request" href="/pull-requests">
    When PRs are opened or updated: link to issue, project column, reviewers, AI description, size/progress sync.
  </Card>
  <Card title="Push events" icon="git-commit">
    On every push: commit notifications on the issue, prefix check, reopen option, size & progress labels (with the configured agent runtime). Details below.
  </Card>
</CardGroup>

---

## 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 branches from the development branch (or main for hotfix/release) based on issue labels (feature, bugfix, docs, chore, hotfix, release). Optional: requires a launcher label (e.g. `branched`) unless `branch-management-always` is true. |
| **Branch–issue linking** | Links the new branch to the issue and adds a comment summarizing the actions taken. |
| **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. |
| **Comments & images** | Posts comments with optional images (per branch type: feature, bugfix, docs, chore, hotfix, release). |
| **Smart workflow guidance** | Comments can include Git-Flow reminders and next steps. |
| **Lifecycle state** | Maintains one setup-provisioned `copilot:state:*` label so the issue visibly moves from analysis to planning and implementation. |

### 2. Pull request events (`on: pull_request`)

When the workflow runs on `pull_request` (opened, edited, etc.):

| Feature | Description |
|--------|-------------|
| **PR–issue linking** | Links the pull request to the issue associated with its branch and posts a comment. |
| **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** | If `ai-pull-request-description` is true and the selected agent CLI is configured, generates or updates the PR description by filling the repo's `.github/pull_request_template.md` from the issue and the branch diff (configured agent CLI). See [Pull Requests → AI-generated PR description](/pull-requests/ai-description). |
| **Comments & images** | Posts comments with optional images per branch type. |
| **Bugbot review** | Reviews the PR on open, edit, reopen, and synchronize events; publishes stable line findings, reconciles resolved/reopened status, and exposes a Check Run. |

### 3. Push events (`on: push`)

When the workflow runs on `push` (e.g. to any branch):

| Feature | Description |
|--------|-------------|
| **Commit notifications** | For branches linked to an issue, posts a comment on the issue with commit messages and links. |
| **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 **comments on the issue** and **review comments on open PRs**; updates issue comments when findings are resolved and **marks PR review threads as resolved** when applicable. Configurable via `bugbot-severity` and `ai-ignore-files`. See [Bugbot](/bugbot), [Issues](/issues#bugbot-potential-problems), and [Pull Requests](/pull-requests#bugbot-potential-problems). |
| **Comments & images** | Posts commit summary comments with optional images. |
| **Finding reconciliation** | Carries stable finding fingerprints across pushes and marks findings fixed, obsolete, dismissed, or reopened without creating duplicate comments. |

---

## Single actions

When you set `single-action` (and, when required, `single-action-issue`, `single-action-version`, `single-action-title`, `single-action-changelog`), the action 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 as comments on the issue and as PR review comments; updates issue comments and marks PR review threads as resolved when findings are fixed. |
| **`recommend_steps_action`** | `single-action-issue` | Uses the configured agent to recommend implementation steps from the issue description; posts a comment 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`** | `single-action-version`, `single-action-title`, `single-action-changelog` | Creates a GitHub release with the given version, title, and changelog. |
| **`create_tag`** | `single-action-version` | Creates a Git tag with prefix `v` (e.g. `v1.2.0`) for the given version from the release branch. |
| **`publish_github_action`** | `single-action-version` | Publishes or updates the GitHub Action: creates/updates the major version tag (e.g. `v2` from `v2.0.4`). Requires `create_tag` to have been run first. |
| **`deployed_action`** | `single-action-issue` | Marks the issue as deployed; updates labels and project state (e.g. "deployed"). |

Single actions that **throw an error** if the last step fails: `publish_github_action`, `create_release`, `deployed_action`, `create_tag`. This lets the workflow fail the job when the action does not succeed.

---

## 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).

<Warning>
Codex is the default runtime for the repository's AI feature paths. OpenCode remains a supported and validated alternative. Cursor is WIP and must not be described as production-validated; see [Cursor runtime (WIP)](/agents/cursor-wip).
</Warning>

| 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 | WIP; authenticated smoke test pending | [Cursor runtime (WIP)](/agents/cursor-wip) |

| Feature | Where it runs | Description |
|--------|----------------|-------------|
| **Check progress** | Push (commit) pipeline; optional single action `check_progress_action` / CLI `check-progress` | On every push, the configured agent compares issue vs branch diff and updates the progress label on the issue and on any open PRs for that branch. |
| **Bugbot (potential problems)** | Push (commit) pipeline; optional single action `detect_potential_problems_action` / CLI `detect-potential-problems` | Analyzes branch vs base and posts findings as **comments on the issue** and **review comments on open PRs**; updates issue comments and marks PR review threads as resolved when findings are fixed. Configurable: `bugbot-severity`, `ai-ignore-files`. |
| **Do user request** | Issue comment; PR review comment | When you comment asking to perform a change in the repo (e.g. "add a test for X", "refactor this", "implement feature Y"), the configured agent applies the changes in the workspace, runs verify commands, and the action commits and pushes with a generic message. Same permission as Bugbot autofix: **only org members or the repo owner**. 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 comments: answers when mentioned (or on any comment for question/help issues). Runs when the comment was not a fix/do request or when the user is not allowed to trigger file-modifying actions. |
| **Explicit Copilot commands** | Issue and PR comments | `/copilot plan`, `/copilot clarify`, `/copilot estimate`, `/copilot test-plan`, `/copilot status`, `/copilot review`, `/copilot findings`, `/copilot recheck`, `/copilot fix`, and `/copilot dismiss` provide a bounded, predictable interface. |
| **Comment translation** | Issue comment; PR review comment | Translates comments to the configured locale (`issues-locale`, `pull-requests-locale`) when they are written in another language. |
| **AI PR description** | Pull request pipeline | Fills the repo's `.github/pull_request_template.md` from issue and 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). |


---

## Workflow concurrency and sequential execution

<Info>
  **Sequential runs:** An admissible mutation run **waits** for any earlier active Copilot/Task mutation run to finish. Runs execute one after another instead of in parallel or being cancelled — something GitHub does not offer natively. Runs triggered by the PAT owner that would only re-trigger the normal pipeline complete before entering this queue.
</Info>

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 new one starts (`cancel-in-progress: true`) and can retain only one pending run. Copilot adds an application-level queue: every started Copilot/Task mutation run waits for earlier active runs, including runs from the other Copilot event workflows, so intermediate issue changes are not discarded by a native concurrency group.

Release and hotfix workflows use a separate first `queue-gate` job. That job invokes
the Action with the internal `queue-gate-only` mode and only the ephemeral
`${{ github.token }}` read permissions; it admits the run and exits before project
composition, agent provisioning, setup, or mutation work. The version-preparation and
publication jobs depend on that gate transitively, so a failed or skipped admission
cannot start a write-capable descendant. The setup templates use `vypdev/copilot@v3`
for this gate and therefore require a published v3 bundle that supports
`queue-gate-only`.

This workflow-level gate is distinct from the ordinary Action-level queue wait: the
latter runs inside a fully constructed Action execution for general Copilot mutation
triggers, while the former is intentionally control-plane-only and must not construct
an execution or publish results.

### 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 performs one paginated repository workflow-runs traversal per poll with `per_page: 100`, then locally filters the active statuses (`in_progress`, `queued`, `requested`, `waiting`, and `pending`), the seven known Copilot/Task mutation workflow names, and runs with a **lower run ID** (i.e. started earlier). For compatibility queries that provide a workflow identifier without names, it uses the workflow-scoped endpoint when the provider exposes it; otherwise it uses the repository endpoint without `workflow_id`.
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 provider page because exact counting must detect
matching runs on later pages. GitHub's current adapter contract cannot safely combine
all seven workflow names, all five active statuses, and the strict lower-ID predicate
in one server-side filter. A full traversal with `per_page: 100` and one sequential
request path reduces fan-out while preserving correctness; deep-history pagination
therefore remains an explicit API-pressure risk, not an early-stop optimization.

So you get a **repository-wide mutation queue**: multiple triggers for the same workflow (e.g. many issue edits) and related Copilot workflows run sequentially. This conservative scope prevents two workflows from changing shared branches, issue metadata, or release state at the same time. Read-only CI may keep its own native concurrency policy.

### Example

```yaml
name: Copilot - Issue

on:
  issues:
    types: [opened, edited, labeled, unlabeled]

jobs:
  copilot-issues:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: vypdev/copilot@master
        with:
          token: ${{ secrets.PAT }}
          project-ids: '2,3'
```

Mutation workflows deliberately do not use a GitHub Actions `concurrency` block: native cancellation retains only one pending run and can discard intermediate issue, branch, or release mutations. Native concurrency 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).