Soumitra Dutta-How do I install a GitHub App on an organization?

[soumitradutta26]

🏷️ Discussion Type

Bug

💬 Feature/Topic Area

API

Body

Hi Everyone, My name is Soumitra Dutta , I'm oxford based an Entrepreneur, Author & Photographer. I’m trying to install a GitHub App on an organization and would appreciate your suggestions.

What is the recommended process for installing a GitHub App on an organization? Are there any specific permissions, settings, or common issues I should check before installation?

If you have experience managing GitHub Apps for organizations, I’d appreciate any tips or best practices you can share.

Regards
Soumitra Dutta

[LuShadowX]

Org owners can install directly. Repo admins can install apps that don't ask for org-level or repository-administration permissions, and only if the org hasn't turned that off. Everyone else gets a Request button instead, which sends it to the owners for approval.

The flow itself:

1. Go to the app's page, https://github.com/apps/<APP-SLUG>, or straight to https://github.com/apps/<APP-SLUG>/installations/new.
2. Pick the org from the account list (easy to fat-finger your personal account here).
3. Choose All repositories or Only select repositories.
4. Read the permissions it's asking for, then hit Install — or Request, if you're not an owner.
5. If it became a request, an owner clears it under Org → Settings → Third-party Access → GitHub Apps.

Same place to change repo access later: Configure next to the app → Repository access → Save. Suspend cuts its access temporarily, Uninstall removes it.

To see what's already installed:

gh api /orgs/YOUR-ORG/installations \
  --jq '.installations[] | {app_slug, target_type, repository_selection}'

{"app_slug":"renovate","target_type":"Organization","repository_selection":"selected"}

You have to be an owner for that call. Worth knowing: it 404s rather than 403s when your token is short on scopes, which is confusing the first time. The headers tell you what it wanted:

X-Accepted-Oauth-Scopes: admin:org, read:org, write:org
X-Oauth-Scopes: repo, workflow

gh auth refresh -h github.com -s read:org fixes that.

A few things that catch people out:

• Only select repositories doesn't pick up repos you create later — you have to add them by hand. The exception is repos the app itself creates.
• If you see Request where you expected Install, an owner has restricted it under Settings → Member privileges → Access ("App access requests", and the "Allow repository admins to install GitHub Apps for their repositories" checkbox).
• If the org uses an IP allow list, switch on Enable IP allow list configuration for installed GitHub Apps first. Otherwise the install looks fine and the app just fails with connection errors afterwards.
• GET /user/installations won't work with a classic PAT — that one needs a user-to-server token from the app's own OAuth flow.

Docs: installing a GitHub App from a third party and reviewing and modifying installed GitHub Apps.

[ayusharnindkumar]

I recently installed a GitHub App on an organisation, and one thing I learned is to double-check the permissions before installing. Also, make sure you're signed in with an account that has Organization Owner access, otherwise the installation can fail or some options won't appear.

If everything looks correct but you're still having trouble, could you share the exact error or where the installation gets stuck? That would make it much easier for others to help.

Hope you get it working soon!