How To Use

Quick installation (CLI)

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

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.

Tutorial: Get Copilot running in three steps

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

• 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:

  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:

    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.

• 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 and Troubleshooting → Bugbot autofix.

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

Priority labels

Size labels

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):

Branch name prefixes (defaults)

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

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

setup/workflows/

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

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

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 and Features & capabilities.