# GitHub

ZPX Forge connects to GitHub through a **GitHub App** that each company installs on its account or
organization, choosing which repos it can see.

## Verified installation

When you come back from GitHub, the installation is only linked if:

1. that same person started it, for that company;
2. they are a company admin in ZPX Forge;
3. they control the GitHub account: it is their own, or they are an admin of the organization.

An installation belongs to a single company.

## Permissions the app requests

| Permission | Why |
|---|---|
| Contents · read and write | Read `specs/`; propose specs through pull requests |
| Pull requests · read and write | Track and open PRs |
| Checks and statuses · read and write | Read or publish checks according to configuration |
| Deployments · write | Approve or reject the commit for a production environment protected by Forge Pro |
| Actions · read | See CI runs |
| Administration · read and write | Protect `main` and `develop` (optional) |
| Members · read | Match organization members |

## Branch protection

From a project, **Protect develop and main** creates a *ruleset* named `ZPX Forge · ramas protegidas`
in the repo: changes only through pull requests, no deletion and no force-push. If it already exists,
it is updated.

## Webhooks and activity

Every delivery is verified with its signature (`X-Hub-Signature-256`), stored only once even if GitHub
retries it, and processed in the background. It becomes project activity:

| GitHub event | Activity |
|---|---|
| `push` | `push` (flags whether `specs/` changed) |
| `pull_request` | `pr.opened`, `pr.merged`, `pr.closed`, `pr.reopened` |
| failed `check_suite` | `check.failed` |
| failed `workflow_run` | `ci.failed` |
| `installation`, `installation_repositories` | Syncs installations and repos |
