---
title: How To Use
description: Quick setup with copilot setup, then customize labels, templates, and workflows.
---

## Quick installation (CLI)

You can install the Copilot CLI **from any directory**. For example, from your home or projects folder:

```bash
git clone https://github.com/vypdev/copilot.git
cd copilot
npm install . -g
```

If the repo does not include the compiled `build/` folder (e.g. it is gitignored), run `npm install` and `npm run build` before `npm install . -g`.

Once installed, the `copilot` command is available globally. **All Copilot CLI commands** (including `copilot setup`, `copilot check-progress -i 123`, etc.) must be run **from inside the repository** where you want Copilot to run. That repository must have a **`.env`** file in its root with **`PERSONAL_ACCESS_TOKEN`** set so the CLI can access the repo. See [CLI commands](/single-actions/workflow-and-cli).

---

## Tutorial: Get Copilot running in three steps

<Steps>
  <Step title="1. Create a PAT">
    The action needs a **Personal Access Token** to manage issues, branches, projects, and workflows. You must create it manually; `copilot setup` does not create it.
    Follow the [Authentication](/authentication) guide to create a **fine-grained PAT** with the right permissions (Actions, Administration, Contents, Issues, Metadata, Pull requests, etc.) and store it as a secret (e.g. `PAT`) in your repository or organization.
  </Step>

  <Step title="2. Run copilot setup in your repository root">
    Go to the **root of the repository** where you want Copilot (clone it if needed), then run:

    ```bash
    cd /path/to/your/repo
    copilot setup
    ```

    **About the token the first time:**  
    The first time you run `copilot setup`, there will usually be **no `.env` file** in that repo with the PAT. The command will copy setup files (workflows, templates, etc.) but may fail or skip the step that needs GitHub access (labels, issue types). In that case:

    - Create a **`.env`** file in the **repository root** with your token:
      ```bash
      PERSONAL_ACCESS_TOKEN=your_fine_grained_token_here
      ```
    - Run **`copilot setup` again**. This time it will have access to the repository and will create labels and issue types.

    Alternatively, you can create the `.env` file with `PERSONAL_ACCESS_TOKEN` and its value **before** the first run and execute `copilot setup` once; it will then complete all steps (copy files + create labels and issue types) in a single pass.

    `copilot setup` will:
    - Create `.github/`, `.github/workflows/`, and `.github/ISSUE_TEMPLATE/` if they do not exist.
    - Copy all files from the Copilot `setup/` folder into your repo (workflows, issue templates, pull request template). Existing files are **not** overwritten.
    - Verify GitHub access using `PERSONAL_ACCESS_TOKEN` from `.env` (or the token you pass when prompted).
    - Create all required **labels** in the repository (type, action, priority, size, progress 0%–100%).
    - Create all required **issue types** in the organization (Task, Bug, Feature, Release, Hotfix, etc.), if your plan supports it.

    After this step you have a working baseline: labels, templates, and workflow files are in place.
  </Step>

  <Step title="3. Adapt files to your repository">
    You can tweak issue templates (text, dropdowns), workflow names, and branch names. The following points are **required** for the GitHub Action to behave correctly; the rest is optional.

    **Required for the action to work:**
    - **Token**: Every workflow that runs Copilot must pass the `token` input (your PAT). Typically you set `token: ${{ secrets.PAT }}` in each Copilot step. Without it, the action cannot create branches, update issues, or call the API.
    - **Workflow file names for release/hotfix**: When an issue has the **deploy** label, Copilot *dispatches* a workflow by **filename**. The action inputs `release-workflow` (default: `release_workflow.yml`) and `hotfix-workflow` (default: `hotfix_workflow.yml`) must match the **exact filenames** in `.github/workflows/`. If you rename `release_workflow.yml` or `hotfix_workflow.yml`, you **must** pass the new names to the action in the workflows that invoke Copilot (e.g. in `copilot_issue.yml` add `release-workflow: 'your_release.yml'` and `hotfix-workflow: 'your_hotfix.yml'`).
    - **Deploy label**: The label that triggers the deploy flow is configured by the `deploy-label` input (default: `deploy`). The issue templates and your usage must use this same label when you want to run the release or hotfix workflow.
    - **Branch names in workflows**: The Commit workflow (push) often excludes the main and development branches from running (e.g. `!master`, `!develop`). If you change the default branch names (e.g. `main-branch: 'main'`, `development-branch: 'develop'`), update the `push.branches` filter in `.github/workflows/copilot_commit.yml` so it excludes those same names; otherwise the action may run on every push to main/develop or never run on feature branches.

    **Optional but keep coherence:**
    - **Labels**: If you change any label input (e.g. `feature-label`, `bugfix-label`, `deploy-label`), use the **same** label names in your issue templates (`labels:` in each `.yml`) and when labeling issues manually. Otherwise the action will not recognize the type or flow.
    - **Branch name prefixes**: The action uses inputs like `feature-tree`, `bugfix-tree`, `release-tree`, `hotfix-tree` (defaults: `feature`, `bugfix`, `release`, `hotfix`) to create branch names. If you change them, branch names will follow the new prefixes; keep templates and docs in sync.
    - **Project columns**: Default column names are "Todo" and "In Progress". If you rename columns in GitHub Projects, set the corresponding action inputs (`project-column-issue-created`, `project-column-issue-in-progress`, etc.) so the action moves issues/PRs to the correct columns.

    **Bugbot autofix (issue/PR comments):** Workflows that run on `issue_comment` or `pull_request_review_comment` (so users can ask the bot to fix reported findings) must grant **`contents: write`** so the action can commit and push. On **issue_comment**, the action resolves the branch from an open PR that references the issue and checks out that branch before applying fixes and pushing. See [OpenCode → How Bugbot works](/opencode-integration#how-bugbot-works-potential-problems) and [Troubleshooting → Bugbot autofix](/troubleshooting#bugbot-autofix).
  </Step>
</Steps>

---

## What lives in `setup/` (and what gets created)

Everything under the `setup/` directory is copied into your repo by `copySetupFiles` (run during `copilot setup`). Below is a desglose of labels (with defaults), issue types, and the contents of `setup/` so you know what you can customize and what must stay consistent.

### Coherence when customizing

If you rename or change any of the following, keep these in sync:

- **Label names** in the action inputs (e.g. in workflow `with:` or in repo/organization variables) must match the **labels** used in issue templates and on issues (e.g. `deploy`, `release`, `feature`).
- **Workflow filenames** for release and hotfix (e.g. `release_workflow.yml`) must match the action inputs `release-workflow` and `hotfix-workflow` wherever you call the action (e.g. in the Issue workflow that reacts to the deploy label).
- **Branch names** (main, develop, feature, bugfix, etc.) must match between the action inputs and any workflow filters (e.g. `push.branches` in the Commit workflow).

---

## Labels created by `copilot setup` (default values)

The setup creates the following labels. Names come from the action input defaults; colors and descriptions are set by the code.

### Type and flow labels

| Input key | Default label name | Purpose |
|-----------|--------------------|--------|
| `branch-management-launcher-label` | `branched` | Triggers branch creation when added to an issue |
| `feature-label` | `feature` | Feature branches |
| `enhancement-label` | `enhancement` | Treated like feature |
| `bug-label` | `bug` | Bug type |
| `bugfix-label` | `bugfix` | Bugfix branches |
| `hotfix-label` | `hotfix` | Hotfix branches (from main at tag) |
| `release-label` | `release` | Release branches (from develop) |
| `docs-label` | `docs` | Docs branches |
| `documentation-label` | `documentation` | Treated like docs |
| `chore-label` | `chore` | Chore branches |
| `maintenance-label` | `maintenance` | Treated like chore |
| `question-label` | `question` | Question issues (e.g. Think action) |
| `help-label` | `help` | Help request issues |
| `deploy-label` | `deploy` | Triggers release/hotfix workflow dispatch when added |
| `deployed-label` | `deployed` | Mark issue as deployed after workflow runs |

### Priority labels

| Input key | Default label name |
|-----------|---------------------|
| `priority-high-label` | `priority: high` |
| `priority-medium-label` | `priority: medium` |
| `priority-low-label` | `priority: low` |
| `priority-none-label` | `priority: none` |

### Size labels

| Input key | Default label name |
|-----------|---------------------|
| `size-xxl-label` | `size: XXL` |
| `size-xl-label` | `size: XL` |
| `size-l-label` | `size: L` |
| `size-m-label` | `size: M` |
| `size-s-label` | `size: S` |
| `size-xs-label` | `size: XS` |

### Progress labels

The setup creates **21 progress labels**: `0%`, `5%`, `10%`, … `100%`. Colors go from red (0%) to yellow (50%) to green (100%). These are used by the Check Progress action and commit steps to update issue progress.

---

## Issue types created by `copilot setup` (defaults)

For organizations that support issue types, the setup ensures these exist (name / description / color from action inputs):

| Type | Default name | Default color |
|------|--------------|---------------|
| Task | Task | blue |
| Bug | Bug | orange |
| Feature | Feature | green |
| Documentation | Documentation | pink |
| Maintenance | Maintenance | purple |
| Hotfix | Hotfix | red |
| Release | Release | yellow |
| Question | Question | gray |
| Help | Help | purple |

---

## Branch name prefixes (defaults)

Used to build branch names (e.g. `feature/42-my-title`). Configurable via action inputs:

| Input key | Default value |
|-----------|----------------|
| `main-branch` | `master` |
| `development-branch` | `develop` |
| `feature-tree` | `feature` |
| `bugfix-tree` | `bugfix` |
| `hotfix-tree` | `hotfix` |
| `release-tree` | `release` |
| `docs-tree` | `docs` |
| `chore-tree` | `chore` |

---

## Contents of `setup/` (workflows, templates, PR template)

### `setup/workflows/`

All `.yml` / `.yaml` files here are copied to `.github/workflows/`. Default filenames and roles:

| File | Purpose |
|------|--------|
| `copilot_issue.yml` | Runs on issue events (opened, edited, labeled, unlabeled, etc.): creates branches, links to projects, assignees, deploy trigger. |
| `copilot_pull_request.yml` | Runs on PR events: links PR to issue/project, reviewers, AI description, etc. |
| `copilot_commit.yml` | Runs on push (all branches except main/develop by default): notifies issue, updates size and progress labels, bugbot. |
| `copilot_issue_comment.yml` | Runs on issue comment: e.g. Think action (answer questions). |
| `copilot_pull_request_comment.yml` | Runs on PR review comment: e.g. translation checks. |
| `release_workflow.yml` | **Manual** (`workflow_dispatch`): release flow (version, changelog, tag, release, deployed). Filename must match the action input `release-workflow` (default: `release_workflow.yml`) so the Issue workflow can dispatch it when the **deploy** label is added. |
| `hotfix_workflow.yml` | **Manual** (`workflow_dispatch`): hotfix flow. Filename must match the action input `hotfix-workflow` (default: `hotfix_workflow.yml`). |

Each Copilot workflow step passes at least `token` (and often `project-ids`, `opencode-model`, `debug` via vars). The **release** and **hotfix** workflows are **dispatched by the action** when an issue has the deploy label and the corresponding release/hotfix context (branch, version, etc.); they are not triggered by issue events directly.

### `setup/ISSUE_TEMPLATE/`

All files here are copied to `.github/ISSUE_TEMPLATE/`.

| File | Purpose |
|------|--------|
| `config.yml` | Issue template config (e.g. `blank_issues_enabled`, contact link to Git-Flow). |
| `feature_request.yml` | Feature request; uses labels like `enhancement`, `feature`, `priority: low`. Add `branched` if you want a branch created automatically. |
| `bug_report.yml` | Bug report; uses `bug`, `bugfix`, `priority: high`. Add `branched` if needed. |
| `doc_update.yml` | Documentation; uses `documentation`, `docs`. |
| `chore_task.yml` | Chore/maintenance; uses `chore`, `maintenance`. |
| `help_request.yml` | Help request; uses `help` (no branch). |
| `hotfix.yml` | Hotfix; uses `hotfix`, `branched`, `priority: high`. Includes Base Version, Hotfix Version, Changelog. |
| `release.yml` | Release; uses `release`, `branched`, `priority: medium`. Includes Release Type, Version, Changelog. |

The **labels** in each template must match the label names configured in the action (or your custom inputs). For example, if you change `deploy-label` to `ready-to-deploy`, then any template or process that adds the deploy trigger must use `ready-to-deploy`.

### `setup/pull_request_template.md`

Copied to `.github/pull_request_template.md`. Used as the default body for new PRs. The AI PR description feature can fill this structure; you can edit the sections (Summary, Related Issues, Scope, Technical Details, How to Test, etc.) to fit your repo. No Copilot logic depends on specific headings; only the deploy/release/hotfix flows depend on **workflow filenames** and **label names**.

### `setup/.env`

If present, copied to the repository root as `.env`. Useful for local CLI (e.g. `PAT=...`). Not used by the GitHub Action (secrets come from the workflow).

---

## Optional: Configure projects, AI, and workflows

After the tutorial and file adaption, you can:

- Set **repository or organization variables** (e.g. `PROJECT_IDS`, `OPENCODE_MODEL`, `DEBUG`) and reference them in the Copilot workflow steps (`project-ids: ${{ vars.PROJECT_IDS }}`, etc.).
- Adjust **project column names** and **branch names** via action inputs so the action moves issues/PRs to the right columns and uses your branch naming.
- Customize **issue templates** (copy, add fields, change labels) while keeping label and workflow names consistent as above.
- Add or modify **release/hotfix** workflow steps (e.g. build, deploy) while keeping the workflow **filenames** and the action inputs `release-workflow` and `hotfix-workflow` in sync.

For a full list of inputs and behaviors, see [Configuration](/configuration) and [Features & capabilities](/features).