GitHub permissions

Warpway asks GitHub for the least access that lets it review pull requests and report results. This page lists every repository permission and webhook event, what Warpway uses it for, and what it cannot do.

Repository permissions

Permission	Access	What Warpway uses it for
Metadata	Read	Required by GitHub for every app: repository names, IDs, visibility and default branch.
Contents	Read	Read files, commits, history and blame at a pull request's base and head commits; download a snapshot of the head commit for the review's read-only tools; read `.warpway.yml` and `CODEOWNERS` from the base branch.
Pull requests	Write	Read pull request details, changed files, commits, reviews and comments; post and edit the single summary comment; mention and request reviewers for human tasks; submit an approving review when auto-approval is enabled.
Checks	Write	Create and update the `Warpway / Review` check run and its annotations; read the results of your other CI checks on the head commit; receive Re-run requests.
Issues	Read	Receive comments on pull requests: GitHub delivers pull request conversation comments as issue comment events, and only to apps with this permission. Warpway reads answers to its questions and `/warpway` commands this way, and reads the issues a pull request links to. It cannot create, edit or close issues.
Members (organization)	Read	Confirm that a person signing in belongs to your GitHub organization (and whether they own it) before granting access to its reviews, and remove access within the hour when they leave. Outside collaborators get no organization-wide access.

The Warpway app does not ask for Actions access. Runtime verification uses a separate app, described below.

Contents is read-only. Warpway cannot push commits, create branches, change files or merge pull requests.

The configuration page can prepare a proposed .warpway.yml and open it in GitHub’s file editor. You review the file, commit it to a new branch with your own GitHub permissions, and choose Propose changes to open a pull request. The configuration takes effect after that pull request is merged.

Account permission

Permission	Access	What Warpway uses it for
Email addresses	Read	Read the verified email of the person signing in, so an Admin can turn on matching Warpway users to Slack members by verified email. GitHub asks for it when you authorize Warpway; it gives no access to repositories.

Warpway does not request the Commit statuses permission: it reads CI results reported as check runs (such as GitHub Actions), but not results a CI service reports only as commit statuses.

Webhook events

Event	Why Warpway subscribes
`installation`	Know when the app is installed, uninstalled, suspended or unsuspended, and when an owner accepts new permissions. GitHub sends it to every app.
`installation_repositories`	Start or stop reviewing repositories as they are added to or removed from the installation. GitHub sends it to every app.
`pull_request`	Review on `opened`, `reopened`, `synchronize` (new commits) and `ready_for_review`. The same event also tells Warpway when a pull request is closed, converted to a draft or edited, for example to change its base branch.
`pull_request_review`	Know when people submit reviews on a pull request.
`issue_comment`	Read `/warpway` commands in pull request comments, such as an answer to a question routed to you on GitHub.
`check_run`	Handle Re-run and the Re-run review button on the `Warpway / Review` check.
`check_suite`	Handle Re-run all checks, which includes Warpway's check.
`github_app_authorization`	Know when someone revokes Warpway's authorization of their GitHub account. GitHub sends it to every app.

Every delivery is verified with GitHub's X-Hub-Signature-256 HMAC signature against the raw request body before it is parsed, and recorded by its delivery ID so a redelivered event is never processed twice.

Tokens

Warpway acts on repositories with installation access tokens that GitHub issues for one hour. Warpway requests them as needed, keeps them in memory only, and never writes them to its database. The GitHub App's private key is held in encrypted environment configuration.

When you sign in, GitHub issues a user token for Warpway that identifies you and lists the installations you can access. Warpway stores it encrypted with your session and uses it to confirm your membership. If you revoke Warpway's authorization in your GitHub settings, the token stops working.

What Warpway cannot do

Push code, create branches, edit files or merge.
Change repository or organization settings, branch protection or rulesets.
Read repository or organization secrets.
Read repositories outside the installation.
Act on your repositories after you suspend or uninstall the app: GitHub then blocks its access and stops sending it events.

Warpway Runtime app

Runtime verification starts your approved verification workflow in GitHub Actions, which needs the Actions: write permission. GitHub App permissions belong to an app as a whole, so if the Warpway app asked for Actions, every organization would have to grant it. Instead, organizations that turn runtime verification on install a second app, Warpway Runtime, that asks for nothing else.

Permission	Access	What Warpway uses it for
Metadata	Read	Required by GitHub for every app.
Actions	Write	Dispatch `warpway-verify.yml` on a pull request's base branch with a profile name, a commit SHA and two Warpway ids; read that run's status; download its `warpway-result` artifact.

Event	Why Warpway Runtime subscribes
`workflow_run`	Learn when a verification run starts and finishes, so results arrive without waiting for the next poll.
`installation`, `installation_repositories`	Know which repositories it was given, and when it is suspended or uninstalled. GitHub sends them to every app.

An Admin installs it from Settings → Runtime verification → Install Warpway Runtime. GitHub shows the permissions and lets you choose repositories; give it the repositories you verify.
Warpway Runtime serves the Warpway organization installed on the same GitHub account, and nothing else. It cannot read code, pull requests or checks; the Warpway app does that.
Before every dispatch Warpway asks GitHub whether Warpway Runtime can reach that repository. If it cannot (not installed, repository not selected, suspended, or Actions not granted), nothing is started and the lenses that need the profile report Incomplete with what to fix.
Uninstalling Warpway Runtime removes all Actions access at once. A verification already running is then reported as not run, never as passed.

Deployments that run their own copy of Warpway can instead create their Warpway app with Actions included; Warpway then uses that installation's Actions access and does not need Warpway Runtime.

Reviewer requests and comments

When a human task is best answered by an engineer, Warpway can request that person or team as a reviewer and mention them in a comment with the question. Admins can turn reviewer requests off for the organization, or limit them per repository with reviewer_requests. People who are reached only in Slack are never requested as reviewers.

Changing permissions

GitHub App permissions belong to the app as a whole: an installation cannot grant a single extra permission on its own. When Warpway's app asks for a new permission, GitHub asks an owner of each installation to approve it. Until an owner accepts, the installation keeps its current permissions: features that need the new one stay off, and any lens that requires it reports Incomplete rather than passing. This is why the optional Actions access lives in the separate Warpway Runtime app instead.