Copilot is a GitHub Action for task management using Git-Flow: it links issues, branches, and pull requests to GitHub Projects, automates branch creation from labels, and keeps boards and progress in sync. Think of it as bringing Atlassian-style integration (boards, tasks, branches) to GitHub.
Full documentation: docs.page/vypdev/copilot
Maintains state and configuration persisted in issue descriptions for seamless workflow automation.
| Section | Description |
|---|---|
| How to use | Step-by-step setup: PAT, copilot setup, workflows |
| Features & capabilities | Workflow triggers, single actions, agent execution, and concurrency |
| Authentication | PAT setup, permissions, token best practices |
| Configuration | All inputs: branches, labels, projects, locale, agents, and more |
| Release orchestration | Production-first release/hotfix flow, npm OIDC, reconciliation, and recovery |
| Agents | Runtime, model, CLI, policy, and failure behavior |
| Security & Operations | Credentials, trust boundaries, provisioning, verification, upgrades, and rollback |
| Development | Architecture, testing, documentation, artifacts, and release process |
The recommended onboarding path is to install the published package globally with
pnpm and initialize the target repository with copilot setup:
pnpm add --global @vypdev/copilot
copilot --version
cd /path/to/your/repository
copilot setup
# Optional local visual assistant, in the same repository:
copilot setup --web@vypdev/copilot contains both the copilot CLI and the compiled GitHub Action.
The global installation makes the CLI and the setup templates available; it does
not install an Action into GitHub. copilot setup is the canonical initialization
flow and will, according to the selected features:
- copy the selected workflows, Issue Forms, pull request template, and repository agent guidance into the repository;
- create the labels and issue types used by the workflows;
- configure non-sensitive Repository Variables; and
- validate or provision the workflow PAT and provider credentials at the selected scope.
The wizard selects issue workflow kinds with a Space/Enter multi-select; All
is the default. It also generates .copilot/repository-profile.json,
.copilot/AGENT_GUIDE.md, and the Codex skill
.agents/skills/copilot-repository-workflow/SKILL.md by default. The generated
guidance makes clear that the Action owns remote branch lifecycle: agents work
on the exact existing branch and push normal commits, but do not create, rename,
delete, replace, or force-push managed branches.
The setup PAT entered by the operator is separate from the workflow PAT Secret.
Interactive setup can guide creation of both via GitHub's prefilled PAT form:
picks the permission-affecting setup options first, then the operator creates a temporary setup token, and the bot account creates the
persistent workflow token. GitHub handles account switching, 2FA, repository
selection, and final creation; Copilot never creates or revokes either token.
Use copilot setup --dry-run to inspect the plan before making local or remote
changes. See the complete How to use
guide and Authentication.
--web opens an ephemeral, loopback-only setup page with a six-stage progress
rail, plan review, separate masked inputs for the two PAT roles, and a
System/Light/Dark theme control. If the browser does not open, use the local
URL printed in the terminal. The page does not create PATs: GitHub owns the
form, account switch, 2FA, and token issuance. You must explicitly approve
the plan and Apply; --web cannot be combined with unattended approval or
secret-bearing command-line flags. The terminal wizard remains the default.
You can integrate the Action manually when the CLI setup flow is not suitable:
copy selected files from setup/workflows/ into .github/workflows/ and add
steps such as:
- uses: vypdev/copilot@v3
with:
token: ${{ secrets.PAT }}This is a lower-level integration path, not an alternative name for
copilot setup: it does not automatically create labels, issue types, Variables,
Secrets, templates, or the complete set of workflows. Those resources must be
configured and kept consistent manually. See Workflow setup
for action-level examples.
- Issues — Branch creation from labels (feature, bugfix, hotfix, release, docs, chore), project linking, assignees, lifecycle/size/progress labels; new issues receive a contextual
@vypbotwelcome; from comments you can ask for help, explain/diagnose/analyze code, plan work, fix findings, or request an authorized implementation. - Pull requests — Link PRs to issues, update project columns, assign reviewers; optional AI-generated PR description and automatic Bugbot review with stable finding threads; use
/copilot analyzeor@vypbot analyze ...for read-only review, or request an authorized change. - Push (commits) — Notify the issue, update size/progress, and optionally run Bugbot; a separate agent-free observer watches every branch and recommends synchronizing children when their parent moves.
- Projects — Link issues and PRs to boards and move them to the right columns.
- Single actions — On-demand maintenance and analysis, plus workflow-owned callbacks for durable release and hotfix operations.
- Branch synchronization — Authorized issue/PR commands merge parent into working branch, call the fixer only for eligible conflicts, run verification, reject remote races, push, and report exactly what happened.
- Release and hotfix orchestration — Cut from the correct immutable origin, promote through a protected production PR, publish only the accepted production commit, and reconcile it back through resumable managed PRs without keeping a runner polling checks.
- Evidence and safety — Every run writes a bounded Job Summary; PR findings are reconciled from GitHub into one status card, historical review status blocks, and a
Copilot / ReviewCheck Run. Actionable findings are neutral by default and fail it only whenbugbot-fail-on-unresolvedis enabled, while unknown/incomplete state always fails closed. Agent sandboxes run without approval or network access, and all agent/comment content remains bounded, secret-redacted, and treated as untrusted data. - Bugbot quality — Hierarchical rules, semantic finding identity, safe GitHub suggestions, analysis-only dry runs, a multilingual regression corpus, real-agent benchmark runner, content-free telemetry/analytics, and the provider-neutral
@vypdev/copilot/bugbotAPI. - Concurrency — Durable mutation workflows wait only for older active runs of that same workflow, with rate-limit-aware polling and a 90-minute deadline. Commit and Pull Request templates share a branch-scoped latest-revision group so a newer Bugbot review supersedes an older one; provider re-reads and head guards make interrupted finding transitions retryable. Event templates can also skip bot-authored jobs before runner allocation through
COPILOT_BOT_LOGIN. See Features → Workflow concurrency.
AI features use the configured agent runtime and qualified model; see the Agents and Security & Operations documentation. You can run progress and Bugbot locally through the Single actions → Workflow & CLI path.
The programmatic Bugbot API is request-only: review(BugbotReviewRequest) is
the sole review entrypoint, and internal runtime aggregates are not exported.
See the Programmatic API.
See CONTRIBUTING.md for development setup, conventions, and how to submit changes.