GitHub App setup

A GitHub App is GitHub's recommended way to grant a service limited access to a repository. Unlike a personal access token, it has its own identity (pullpress[bot]), its permissions are fixed and visible, and you can restrict it to exactly the repositories you choose.

What permissions it asks for

During installation GitHub shows you the full permission list. It is deliberately short:

• Contents — read & writeRead your content files and commit editors' changes to branches.
• Pull requests — read & writeOpen, update and label the pull requests editors submit.
• Metadata — readBasic repository information (name, default branch). Required for every GitHub App.
• Workflows, Actions, settings, secretsExplicitly not requested. PullPress cannot modify your CI, repository settings, webhooks or secrets.

Installing on one repository

• In your PullPress dashboard, choose Connect a repository. You are sent to GitHub's installation screen.
• Pick the account or organization that owns the repo, then choose Only select repositories and select the one repository for your site. You can always add more later.
• Review the permissions and confirm. GitHub redirects you back to PullPress, which now sees the repository.

Back in PullPress, the connect screen first confirms which account the installation covers and how many repositories it can reach — with a direct link to change the installation on GitHub if it landed on the wrong account or the wrong repositories. If you cancel the GitHub flow halfway, PullPress shows a friendly “installation wasn't completed” note with a retry link instead of failing silently.

Organization admins can also install the App for a teammate: PullPress picks up the installation as soon as it exists.

How an installation maps to a site

One connected repository becomes one sitein PullPress. The site reads its content model from the repo's pullpress.config.yml, and every editor you invite is invited to that site specifically. Agencies with many client repos get one site per repo, all visible in the multi-site dashboard, each with its own editors and roles.

Security notes

• Path allowlists. PullPress only ever writes inside the folders your config declares — collection folders and the media folder. It refuses to touch anything else, including .github/.
• No tokens in the browser. Editors' browsers talk only to PullPress. GitHub credentials are short-lived installation tokens that exist server-side and are never sent to the client.
• Every change is attributable. Commits and pull requests are created by pullpress[bot] and credited to the editor who made them, so your Git history stays meaningful.
• Revocable in one click. Uninstall the App from your GitHub settings at any time. Access ends immediately and your content stays exactly where it is. PullPress notices, too: an uninstalled or suspended installation shows up as a status badge on the sites list and a dashboard alert, and the workspace admins are emailed within minutes — no silent breakage.
• Missing permissions are named. If the App ever lacks a permission it needs (for example after an updated permission set you haven't accepted yet), the error names the exact missing scope instead of failing generically.

Next step: describe your content in pullpress.config.yml, or walk through the full setup in Getting started.