# Permissions

> Who can see and change what in Pullfrog, based on each person's GitHub role.

Pullfrog takes every permission from GitHub. There is no user list, invite step or seat to manage: a teammate signs in with GitHub and sees the organizations and repositories they can already reach.

## Roles

| GitHub role | What it allows in Pullfrog |
| --- | --- |
| Repo read | Open the repo console and view active and past runs. |
| Repo write | Trigger runs from the console prompt box. Set the repo up. Edit the **Model**, **Hooks**, **Learnings** and **Flags** cards and everything under **Automations**. Disable and re-enable Pullfrog on the repo. |
| Repo admin | Edit the **Security** card (code pushes, signed commits, shell isolation, environment allowlist) and the **Secrets** card. Turn on **Auto-merge approved PRs** and Pullfrog for OSS. |
| Outside collaborator | See only the repos they collaborate on in the organization console, with no organization-wide cards. Their repo role applies in each repo console. |
| Org member | Edit the organization **Model** card and, under **Advanced**, **Standing instructions**, **Cross-repo brief**, **Cross-repo learnings** and **Flags**. View **Analytics** on the Organization plan. |
| Org owner | Manage **Plan and payment**, **Providers** and **Secrets**: the plan, payment method, Pullfrog Router credit, and account-level provider keys and secrets. View the billing and Router history pages. |

The roles combine in three ways:

- Each repo role includes the ones above it, so an admin can do everything a write user can.
- Organization roles are separate from repo roles: an org member still needs write access to change a repo's settings.
- On a personal account, the account owner holds every role.

## Notes

- **Repo setup.** Adding `pullfrog.yml` needs write access to that repo, not an organization role. The commit is made as you; if the default branch is protected, Pullfrog opens a pull request from `pullfrog[bot]` instead. A private repository in an organization still needs a [plan](https://pullfrog.com/docs/billing) that covers it.
- **Locked cards.** A card you cannot edit stays in place with a lock icon and a short message naming who can change it, so links into the console still resolve. The API enforces the same rules, so billing data never reaches a non-owner's browser.
- **Organization-wide reach.** Organization standing instructions and flags apply to every run in every repository of the organization, including [flags](https://pullfrog.com/docs/flags) that set the model or timeout. Any org member can edit them; outside collaborators cannot.
- **Org owners.** Pullfrog reads the owner role from GitHub again before billing changes instead of trusting a cached value. GitHub's API calls this role `admin`.

## Custom GitHub App

An organization on the Enterprise plan can register a custom GitHub App and run Pullfrog through it instead of the shared `pullfrog` App. [Contact us](mailto:sales@pullfrog.com) to enable it for your organization.

- The App lives in your organization's settings. You control and audit its permissions, and you revoke it by deleting it.
- Runs act as `<your-app>[bot]`.
- An organization policy that blocks third-party Apps is satisfied because the App is yours, and the shared App never has to be installed.

To register it:

1. On the console's home page, click **Add organization**, choose **Use a custom GitHub App**, and enter the organization's login. An org admin of an organization that already uses Pullfrog can instead expand **Advanced** in the organization console and click **Register custom GitHub App**.
2. GitHub shows its own App creation page, filled in with Pullfrog's permission set. GitHub admits only the organization's owners and App managers to that page.
3. GitHub creates the App on your organization and hands its credentials to Pullfrog directly, so nothing is uploaded. You are then taken to the install page.

Repos you had already set up keep their settings, learnings and history. After the switch:

- **Mentions.** Runs start on `@pullfrog` and on your App's own handle, such as `@acme-bot` if you renamed the App.
- **Runs switch when your custom App is installed.** Pullfrog then ignores the shared `pullfrog` App for your organization, so you can uninstall it. The switch covers the whole organization: a repo left out of your custom App's repository selection stops running Pullfrog.
- **Each member authorizes your custom App once.** The first time a member opens your organization console after the switch, GitHub asks them to authorize your custom App, which is how the console reads your organization through it. Until then your organization is missing from their console list, so share the direct link: `pullfrog.com/console/<your-org>`.
