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.
• Organization members — readOnly used to check whether the person connecting is an owner of your GitHub organization, which is what allows them to move an installation away from a workspace that shouldn't have it.
• Checks — read (optional)Lets the dashboard show whether your site is building or live after a change. Leave it off and everything else works the same.
• 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 website (or Connect site on the Sites & GitHub page). 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 asks you to authorize PullPress for your GitHub account and redirects you back.

That authorization step is how PullPress checks that you really have access to the installation before it is tied to your workspace: it asks GitHub which installations of the App your GitHub account can reach and only accepts those. Nobody can attach your repositories to their workspace by guessing an installation number, and an installation already connected to another workspace by a different GitHub user is refused.

Access to an installation isn't access to every repository in it, so PullPress also asks GitHub which repositories your account can push to. Only those are offered when you add a site, and the check is repeated on the server. It stays valid for a week; after that one click on Refresh my repository access re-checks it with GitHub.

Once a site exists it keeps working through the App, even if the person who connected GitHub later leaves your organization. So every 180 days PullPress asks a workspace admin to confirm the connection again: the Sites page shows Confirm again by… two weeks ahead, owners and admins get one email, and Verify with GitHub next to the installation takes care of it in one click. It is a reminder only — editing and publishing are never blocked.

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. The teammate then opens the connect screen (or the Sites page) and chooses Verify with GitHub (or Connect an existing installation): GitHub confirms their access and the installation is ready to use. If your GitHub account reaches several installations, you pick the one this workspace should use — PullPress never connects them all at once. Installations connected before this check existed ask for the same one-time verification before new sites can be added on them.

If an organization member requests the App instead of installing it, PullPress tells you the request is waiting for an organization owner; once it is approved, use Connect an existing installation.

Disconnecting and taking over

Workspace owners can Disconnect an installation on the Sites page once no active site uses it. Nothing changes on GitHub.

If another PullPress workspace holds an installation on your GitHub account or organization, an owner of that account can move it to their own workspace (as a PullPress workspace owner — workspace admins see the option but need an owner to confirm it): GitHub confirms they are an owner, the other workspace's sites on it are archived (read-only) and its owners are emailed. Both disconnects and takeovers are recorded in the workspace audit log.

How an installation maps to a site

One connected repository becomes one site in 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. Editors' changes are only ever written inside the folders your config declares — collection folders and the media folder. Beyond those, PullPress writes just two files of its own: its pullpress.config.yml (when an admin sets up or edits the configuration) and, if you use it, an llms.txt at the repository root. Both configuration changes and the automatic upkeep of an existing llms.txt on open-publishing sites are committed directly to your default branch; the manual “Update llms.txt” button on other sites goes through review. Anything else, including .github/, is refused.
• 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. The GitHub authorization used to check access when connecting runs with PKCE and is revoked as soon as the check is done; PullPress keeps no GitHub user tokens.
• 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. By default the author is the editor's name with a pseudonymous no-reply address (id+name@users.noreply.…), so email addresses never end up in a public repository's history. A site admin can switch to real email addresses under Site settings → Use editors' real email addresses in Git history.
• 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.
• Branch previews build editor content. Changes waiting for review live on their own branch. If your host builds a preview of every branch (Netlify, Vercel, Cloudflare Pages…), that preview runs your site's build on not-yet-reviewed content. PullPress blocks editors from adding scripts or MDX code, and only real JPG/PNG/WebP images can be uploaded. Still, don't expose production secrets to preview or branch builds, and keep administrator rights (who may add code) for people you trust.
• 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.