# 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

| 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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

### 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

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

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

If you have questions about Avrea's GitHub access, or want to report a
security issue, contact [security@avrea.com](mailto:security@avrea.com).
For policies, certificates, and live security posture, visit the
[Avrea Trust Center](https://trust.avrea.com).