GitHub App Permissions
Avrea uses two GitHub Apps with the same control-plane implementation. The Repository App registers runners for individual repositories and therefore needs repository Administration access. The Organization App registers runners in an organization runner group and requests the narrower organization Self-hosted runners permission instead. The current registration manifest shares all other permissions between the two Apps.
This page describes the baseline for new App registrations. Existing installations retain their previously approved grant until an organization owner accepts newly requested permissions.
How Avrea limits what those permissions can do in practice:
- Avrea authenticates with short-lived installation tokens — GitHub expires them after about an hour, and Avrea caches them for less than their lifetime.
- For narrowly targeted operations, Avrea mints tokens scoped down to a single repository and only the permissions that operation needs. GitHub enforces the reduced scope server-side, so such a token cannot do more even if mishandled.
- Avrea never pushes to your default branch and never merges anything. The only writes to repository contents happen on a new branch behind a pull request that you review and merge.
Repository permissions
Section titled “Repository permissions”| Permission | Access | Used for |
|---|---|---|
| Metadata | Read | Baseline required by every GitHub App |
| Actions | Read and write | Run history; re-run, dispatch, and cancel runs |
| Variables | Read | Reserved for workflow conversion and compatibility diagnostics |
| Environments | Read | Reserved for deployment-configuration compatibility checks |
| Administration | Read and write | Repository App only: registering and removing just-in-time runners |
| Checks | Write | Surfacing jobs Avrea rejects before a runner starts |
| Contents | Read and write | Pinning runs to exact commits; opening PRs you request |
| Issues | Read | Receiving pull request conversation comment events |
| Pull requests | Read and write | Opening those PRs; PR status comments; conversation sync |
| Workflows | Write | PR changes that touch files under .github/workflows/ |
Metadata (read)
Section titled “Metadata (read)”The implicit baseline GitHub requires of every App in order to see a repository at all. Avrea also uses it to check that a user acting on a repository through Avrea actually has access to that repository on GitHub.
Actions (read and write)
Section titled “Actions (read and write)”Read access lists workflows, workflow runs, and their jobs to keep run history current in the console. Write access powers the console's dispatch, re-run, and cancel buttons. Avrea also cancels an in-flight run itself when it has to reject the underlying job — for example over a queue limit or a billing hold — so the run fails fast instead of hanging until GitHub's timeout, and you are not billed for work that cannot complete.
Variables (read)
Section titled “Variables (read)”Reserved for workflow conversion and compatibility diagnostics that need to
resolve ${{ vars.* }} references. GitHub variables are not secrets, and the
API returns their values. Avrea treats those values as customer configuration
and does not request permission to create, update, or delete variables.
Environments (read)
Section titled “Environments (read)”Reserved for checking environment-specific workflow configuration. This can read environment variable values plus secret names and metadata, but never secret values. This permission does not authorize changes to environments, variables, secrets, protection rules, or deployment branch policies, and Avrea does not make those modification calls.
Administration (read and write)
Section titled “Administration (read and write)”GitHub gates self-hosted-runner registration behind the repository Administration permission — there is no narrower scope for it. Avrea uses this permission exclusively to register and remove the just-in-time runners that execute your jobs. It never reads or changes repository settings, branch protection, collaborators, or anything else this permission would technically allow.
Checks (write)
Section titled “Checks (write)”When Avrea must reject a job before any runner exists — for example when a queue limit is reached — it publishes a check run on the triggering commit. Without this, a job that never started would fail invisibly.
Contents (read and write)
Section titled “Contents (read and write)”Read access resolves branches and tags to exact commit SHAs so every run is pinned to the precise commit it was triggered for, and reads workflow files for features you invoke (such as workflow conversion).
Write access is used by exactly two features, both of which you trigger explicitly: workflow conversion and dependency-pinning pull requests. Both create a new branch, commit the change there, and open a pull request for your review. The branch is deleted again if the pull request is not created. Avrea never commits to an existing branch.
Issues (read)
Section titled “Issues (read)”GitHub treats a pull request's conversation thread as issue comments, and delivers those comment events only to Apps holding read access to Issues. That subscription is the sole reason this permission is requested: comments on issues that are not pull requests are ignored, and Avrea never creates or edits GitHub Issues — its comments appear only on pull requests.
Pull requests (read and write)
Section titled “Pull requests (read and write)”Write access opens the pull requests described above, and posts a comment on a pull request when one of its jobs could not be run — stating the reason, such as a queue limit or a billing hold — so the outcome is visible where you work. Comments are deduplicated, so a large fan-out workflow cannot flood a pull request.
Read access keeps pull request metadata and conversations in sync for the console.
Workflows (write)
Section titled “Workflows (write)”GitHub requires this permission in addition to Contents for any change to
files under .github/workflows/. It is needed when a pull request opened
by Avrea contains a converted or pinned workflow file. Tokens minted for
pull requests that do not touch workflow files do not carry this
permission.
Organization permissions
Section titled “Organization permissions”Self-hosted runners (read and write)
Section titled “Self-hosted runners (read and write)”Required only when Avrea runners are registered against an organization-wide runner group rather than a single repository, which also requires the App to be installed at the organization level. Used to create and remove runner registrations and to list the organization's runner inventory. Unused for repository-level installations.
Webhook events
Section titled “Webhook events”Every webhook delivery is verified against the App's webhook secret (HMAC-SHA256 signature) before it is processed.
| Event | Why Avrea receives it |
|---|---|
workflow_job | The core signal: a queued job with an Avrea runner label triggers provisioning of a fresh runner |
workflow_run | Keeps workflow and run metadata current |
pull_request | Keeps pull request metadata current |
issue_comment, pull_request_review, pull_request_review_comment, pull_request_review_thread | Keep pull request conversations and review verdicts in the console in sync |
push | Triggers mirror sync for repositories with mirroring enabled |
installation, installation_repositories | Track which repositories the App is allowed to act on |
installation_target | Updates the stored account name when a user or organization is renamed |
repository | Applies repository visibility, archive, and deletion changes promptly |
check_run, check_suite, github_app_authorization, ping | Automatic GitHub deliveries that Avrea acknowledges and intentionally discards |
issues | Legacy delivery that existing Apps may still send and Avrea intentionally discards; new Apps must not subscribe |
Unexpected event types are acknowledged, recorded as unsupported traffic, and discarded.
Sign-in uses a separate OAuth app
Section titled “Sign-in uses a separate OAuth app”Signing in to the Avrea console with GitHub uses a separate OAuth app with
only the user:email scope. It reads your GitHub profile and verified
email address to create or link your Avrea account. It grants no access to
repositories and is independent of the GitHub App permissions above.
Questions
Section titled “Questions”If you have questions about Avrea's GitHub access, or want to report a security issue, contact security@avrea.com. For policies, certificates, and live security posture, visit the Avrea Trust Center.