Copilot connects the work described in a GitHub issue to its branch, implementation, pull request, review, and release. It combines a GitHub Action for repository automation with a local CLI and web setup assistant. Enable the capabilities your team needs, including optional AI analysis and code changes.
| Your goal | What Copilot provides | Start here |
|---|---|---|
| Organize work from issues | Issue Forms, Action-managed branches, lifecycle labels, progress, and GitHub Projects updates | Manage issues and branches |
| Review pull requests | Bugbot findings near the code, a current review status, optional PR descriptions, and explicit requests to fix findings | Review PRs and resolve findings |
| Ask for help or implementation | Commands to explain code, diagnose problems, plan work, or apply an authorized change and run verification | Work with the bot |
| Keep working branches current | Drift notices and an authorized synchronization command that verifies the merge before pushing | Branch synchronization |
| Ship releases and hotfixes | Frozen source revisions, protected promotion PRs, version tags, GitHub Releases, and reconciliation back to development | Release and hotfix guide |
For example, a maintainer starts an admitted issue with in-progress. Copilot creates and verifies its branch. A developer or an authorized bot request contributes changes on that exact branch. A linked PR receives review findings and runs the repository's checks. After an authorized merge, a separately launched release can promote the accepted production commit and reconcile it into development.
flowchart LR
I[Issue and plan] --> B[Verified working branch]
B --> C[Developer or authorized bot changes]
C --> P[Linked PR and review]
P --> M[Protected merge]
M --> R[Explicit release or hotfix]
R --> D[Development reconciliation]
AI capabilities require a configured agent runtime, an allowed model, and working authentication on the selected runner. Code-changing requests require repository write authority and run configured verification before commit/push. Release promotion follows the repository's merge policy. Installing Copilot does not grant permission to merge or deploy.
Use Node.js 24 or newer, pnpm, and a working checkout of the repository you want to configure:
pnpm add --global @vypdev/copilot
copilot --version
cd /path/to/your/repository
copilot setup --webThe CLI opens a local browser page. Pair it with the code printed in the terminal, confirm the target repository, and choose Basic guided setup. The assistant explains the required permissions, guides the two separate PAT roles, and shows the files and GitHub resources affected before you approve changes.
- The temporary setup PAT belongs to the operator and is used locally to configure the installation.
- The persistent workflow PAT belongs to the bot account and is stored as the Actions Secret
PAT. - GitHub creates both tokens in its own tabs. The assistant never creates or revokes them.
Follow the web setup tutorial through installing the generated files and verifying the result. Then complete the first issue-to-PR workflow. A local configuration check alone does not prove that an Action can run successfully.
copilot setup without --web launches the terminal assistant. Use copilot setup --web --dry-run for a no-change preview. The npm package installs the CLI and templates; running setup and installing its generated files enables the Action in your repository.
| You need… | Documentation |
|---|---|
| A short installation checklist | Quick start |
| A walkthrough of browser setup | Set up with the web assistant |
| Observable proof that the installation works | First workflow |
| A guide for a specific outcome | Choose a goal |
| Version selection, contextual or offline help | Use the documentation |
| Token ownership, permissions, or account recovery | Authentication |
| Existing-installation updates, batch setup, or manual integration | Setup and maintenance reference |
| Every feature, input, and operational control | Capabilities, Configuration, Security & Operations |
Setup installs the selected workflows, Issue Forms, labels, issue types, Variables, credentials, and repository agent guidance. Projects, agent routing, release/hotfix workflows, and other capabilities follow your selections. New setup offers PR approval assessment in recommend mode; native bot approval requires explicitly selecting guarded and meeting its prerequisites. See guarded approval.
Release templates are registry-neutral. Publishing your application or package requires your own build, validation, and deployment steps. This repository's npm publishing workflow is an example, not something setup installs into every consumer repository.
For a manually maintained workflow, use vypdev/copilot@v3 and supply token: ${{ secrets.PAT }}. Follow the manual integration instructions to install the supporting resources and event workflows.
The request-only @vypdev/copilot/bugbot API is documented in the programmatic API guide. For local commands, see Workflow & CLI.
See CONTRIBUTING.md for development setup and contribution requirements.