GitHub integration

PWR works on your code through a GitHub App. Each installation belongs to exactly one PWR organization, and each project connects exactly one repository. Access tokens are created per use, scoped to that one repository, and never stored.

Status: Implemented and tested end to end against a simulated GitHub, including a browser test with real model runs. Verification against live GitHub is pending, so differences from the real GitHub API would only surface on the first live run.

Install and claim the App

Admins and owners can connect GitHub.

1. Open a project's Repository tab, or Settings → Repositories, and choose Install GitHub App.
2. GitHub asks which account and repositories to install on, then sends you back to PWR Studio.
3. PWR claims the installation for your organization and shows the account, repository selection and ownership proof.

The claim requires proof that you control the GitHub account. For a personal account you must be that user; for a GitHub organization you must be an active admin. Being a collaborator on one of its repositories is not enough. The proof is checked at claim time only.

Permissions the App requests

Importing GitHub Issues additionally needs the Issues permission. See Jira integration.

Connect a repository

Pick a repository from the installation and connect it to a project. It becomes the project's workspace source. PWR then discovers README.md, CLAUDE.md, AGENTS.md, CONTRIBUTING.md and docs/*.md and proposes them as project knowledge. Only entries an admin approves are given to agents.

From task to pull request

task queued → clone default branch, pin base commit, create task branch
            → agent implements in the workspace
            → validation command (recorded by PWR, not the agent)
            → secret scan → commit → push
            → pull request opened → CI snapshot → independent review
            → human approve / request changes / reject
            → merge gate → merge pinned to the reviewed commit → task completed

• Branches are created by PWR, one per run, and are never your default branch. A retry reuses the same branch and continues from it. PWR never force-pushes.
• The agent never holds your repository token. The worker pushes after the agent has exited.
• Secret scan. If the change contains a known secret value or a well-known key pattern, nothing is committed or pushed and the workflow stops at push_failed.
• Pull requests are titled with the task title and marked as opened by PWR. The body lists the task, agent, base commit, changed files, the validation result as recorded by PWR, and the agent's own summary labelled as an unverified self-report.
• If validation fails and is required, nothing is pushed.

CI snapshots

A CI snapshot is a copy of GitHub's check runs and Actions workflow runs for one commit. It is taken after the pull request opens, when GitHub sends check webhooks, and when a developer refreshes it manually. There is no polling loop. A snapshot for an older commit never counts.

Required checks are your policy's required_checks combined with the base branch protection's required status checks. With ci_mode set to required (the default) the gate stays blocked until required checks exist and pass. if_configured passes when the repository reports no checks.

Independent review

A separate reviewer run starts on a fresh clone of the exact commit, with read-only tools (Read, Grep, Glob) and its own instructions. It returns a verdict (approve, revise or block), findings with severities, and a rating in eight categories including correctness, security, test adequacy and scope compliance.

PWR enforces the verdict rules itself: an approval that lists a critical or high finding is recorded as revise, and a verdict that cannot be parsed fails closed. It is never treated as approval.

By default the reviewer uses the same agent definition as the implementer: separate run, clone and tools, but the same model family and credential. Set a dedicated reviewer agent in the project's workflow policy for stronger independence.

Human approval

Under Approvals, open a task to approve, request changes or reject. Every decision is bound to the head commit. Deciding on an outdated commit returns 409 head_mismatch. When new commits arrive, reviews and approvals for the old commit are invalidated and an approved task returns to review.

The merge gate

Merging evaluates 11 checks for the current commit:

1. head_current: the commit you named is still the pull request head on GitHub
2. pull_request_open
3. task_state: the task is approved and not cancelled, rejected or failed
4. validation
5. ci
6. independent_review
7. human_approval
8. role: your role meets the policy's merge role
9. repository_authorized: the installation and connection are active
10. branch_protection
11. no_uncertain_operations

A blocked merge lists the failed checks. Human approval is always required and auto-merge is locked off.

Branch protection that requires approving reviews on GitHub cannot be satisfied by PWR approvals. The gate reports this and blocks.

Workflow policy

Each project has a policy on its Workflow policy tab (admin to change).

Revoking access

Uninstalling or suspending the App on GitHub, or removing a repository from it, makes the affected connections unusable. Runs are refused and the merge gate fails repository_authorized. An owner can also revoke an installation in PWR; that does not uninstall the App on GitHub.

If an operation's outcome is unknown, for example GitHub returned a server error during a push, the task moves to needs_reconciliation. See Troubleshooting.