The Facets GitHub App
How the Facets GitHub App installation works, what "GitHub org approval needed" means, and what to know before changing the installation on GitHub.
Overview
When you link a GitHub VCS account in app mode, the Facets GitHub App is installed on your GitHub organization. That installation is the credential behind Facets' GitHub-backed features.
For an organization-level installation, Facets never stores a long-lived token. It mints a short-lived installation access token on demand instead. This is why an app-mode VCS account has no editable credential: to change one, you re-link the account rather than edit it.
This page covers GitHub VCS accounts linked in app mode. Personal Access Token accounts, and GitLab or Bitbucket accounts, connect through a different mechanism.
To link a GitHub account in the first place, see Integrating Git Accounts.
One Installation, Shared With Praxis
A single GitHub App installation on your organization serves more than one consumer.
| Consumer | What it does with the installation |
|---|---|
| Blueprint sync | Syncs infrastructure configuration between Facets and your repositories |
| Module CI | Runs continuous integration against your modules repository |
| Praxis agents | Where your organization has been moved onto the shared installation, agents read and clone repositories through it. Once a GitHub org admin approves the updated permissions, they also push commits, open pull requests, and edit workflows |
The move onto the shared installation is initiated from Praxis; Facets has no migration control of its own. To check the installation's health from the Facets side, look at the account row on the Accounts page.
For the Praxis side of this story — how agents connect to Git and what moving onto the shared installation involves — see Praxis.
Permission Approval
Facets checks whether the installation holds every permission a dependent feature needs. When the app has requested updated permissions and no GitHub organization admin has approved them, that feature cannot use them. The account row carries the current state:
| State | What you see on the account row | What to do |
|---|---|---|
| Up to date | Nothing | Nothing. The dependent feature can run |
| Approval pending | A Permissions update pending chip | Resolve it with the steps below |
| Not installed | Nothing. A dependent feature that checks reports the app is not installed on the organization | Re-link the account, then approve the requested permissions |
Personal Access Token accounts always read as up to date, because there is nothing to approve. The signal is GitHub-only by design: a GitLab or Bitbucket account has no equivalent state, and Facets rejects the check for those providers rather than reporting them as ready.
Clicking the chip opens the GitHub org approval needed card, which lists each missing permission with a plain-English reason. From there:
- If you are a GitHub organization admin, open the GitHub approval page from the card and approve there.
- If you are not, copy the approval link from the card and send it to an admin.
- Once approved, re-check the status from the card.
Facets cannot approve on your organization's behalf, because GitHub exposes no API for it. Approving is a GitHub-side role, and no Facets permission substitutes for it. Status is cached for 30 seconds per account, so the chip can lag briefly behind an approval; re-checking from the card bypasses that cache.
What the Modules Repo Needs
Permission checking is per feature, not global. The modules repo is the only Facets feature with a declared GitHub App permission requirement today, so an approval prompt is usually about it. A modules repo setup that fails reporting pending permissions is the same approval, surfaced from the other side.
| Permission | Why it is needed |
|---|---|
contents:write | Clone and push |
workflows:write | Push workflow files |
secrets:write | Provision Actions repository secrets |
actions:read | Read workflow run status |
A stronger grant satisfies a weaker requirement: admin outranks write, and write outranks read. An installation granted more than the minimum still reads as up to date.
Before You Change the Installation on GitHub
Repository selection belongs to GitHub, not to Facets. Facets reads and displays the selection; there is no per-repository allowlist managed inside Facets.
Narrowing the repository selection, or uninstalling the app, affects everything that draws on that installation. Check what depends on it before you change it.
The linking guide notes that you do not need to grant access to your code repositories. That still holds for Facets-only use. Where the installation is shared, any repository a Praxis agent works on must sit inside the selection.
Troubleshooting
| Problem | What to do |
|---|---|
| The approval card offers no link yet | Re-check in a moment, or open the app's installation settings on GitHub |
| The linking popup never completes | Polling stops after five minutes. Common causes are a duplicate account name, insufficient permissions, the installation not being finished in the popup, or a network interruption |
| Linking fails with "An account with this name already exists. Please select a unique name!" | Account names are unique across the organization |
Who Can Do What
| Action | Permission required |
|---|---|
| View accounts and their permission status | Read access to accounts through your assigned role |
| Add or re-link a VCS account | Write on the Accounts category |
| Delete a VCS account | Delete on the Accounts category |
Approving GitHub App permissions is the exception, since that is a GitHub role rather than a Facets one. For how these categories map to roles and user groups, see Permissions Reference. Facets audits account creation, updates, and deletion.
Related
- Modules Repo - Back the module registry with a git repository, and what the migrate and attach routes install
- Integrating Git Accounts - How to link a GitHub, GitLab, or Bitbucket account
- Accounts - Cloud and version control account management in Facets
- Praxis - The agents that draw on the same GitHub App installation
Integrating Git Accounts
Link GitHub, GitLab, or Bitbucket accounts to Facets for GitOps workflows, with step-by-step instructions and interactive walkthroughs for each provider.
Project
Projects are the workspace in Facets that holds your blueprints and environments. Learn to create projects, define project types, and manage project settings.