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, images, etc. |
| 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@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 required workflows, issue templates, and pull request template 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 setup PAT entered by the operator is separate from the workflow PAT Secret.
Use copilot setup --dry-run to inspect the plan before making local or remote
changes. See the complete How to use
guide and Authentication.
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.