Source Code Management

GitHub Integration

Ploy offers three ways to connect GitHub, depending on whether you use GitHub.com or GitHub Enterprise.

Integration methods

1. Ploy GitHub App (non-enterprise)

The default method for GitHub.com organizations using Ploy's hosted GitHub App.

Setup steps

  • Click Install GitHub App in the Ploy setup modal. This redirects to GitHub.

  • On GitHub, select the organization you want to connect.

  • Choose which repositories to grant access to.

  • Click Install. GitHub redirects back to Ploy with the installation ID.

  • Enter your GitHub Organization Name, for example my-org.

Permissions are managed by Ploy's GitHub App. You do not need to configure them manually.

Besides members, teams and repositories, the app reads app installations, deploy keys, Actions secret names (never values), fine-grained personal access tokens, and your organization's GitHub Copilot and plan seats, which Ploy shows as licenses.

When Ploy's app asks for a new permission, GitHub asks an organization owner to review and accept the request. Until it is accepted, Ploy skips that data and scans everything else normally.

2. Enterprise — Personal Access Token (PAT)

Use this for GitHub Enterprise Cloud, GHE.com, or self-hosted GitHub Enterprise Server.

Create the token in GitHub

  • Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic).

  • Click Generate new token (classic).

  • Set a descriptive name, for example Ploy Integration.

  • Select these scopes: read:enterprise, read:org, repo.

  • Click Generate token and copy it.

The PAT must belong to an enterprise owner.

With these scopes Ploy also reads app installations, deploy keys, Actions secret names (never values), SAML SSO-authorized tokens and SSH keys, and Copilot seat assignments. Organization-level Actions secrets need admin:org, which is optional.

Configure in Ploy

  • Enable the GitHub Enterprise toggle.

  • Enter your GitHub Domain: github.com for Enterprise Cloud, or your self-hosted domain for GitHub Enterprise Server, for example github.mycompany.com.

  • Enter your Enterprise Slug. This is the enterprise account name visible in your enterprise URL, for example github.com/enterprises/your-slug.

  • Select Personal Access Token (PAT) as the Authentication Method.

  • Paste the token into the Personal Access Token field.

  • Enter your Primary Organization (required). This is the GitHub organization where Ploy will create users, manage memberships, and run other actions. Ploy will still scan members, teams, and repositories across every organization in your enterprise, but actions (joiner/leaver flows) target this organization only.

3. Enterprise — Customer enterprise GitHub App

This is the most secure method. Your team creates and manages its own GitHub App and installs it on the enterprise.

A. Create the GitHub App

Create the GitHub App in the enterprise, not on the organization level. If you create it on an organization instead, you will not be able to install it on the enterprise, and the integration will not work.

  • Go to your enterprise on GitHub, for example github.com/enterprises/your-slug, then Settings → GitHub Apps → New GitHub App.

  • Configure the app:

  • App name: for example Ploy Integration (your-company).

  • Homepage URL: your company URL.

  • Webhook: clear Active. This is not needed.

  • Set these permissions:

  • Organization permissions → Members: Read & Write.

  • Organization permissions → Administration: Read-only.

  • Repository permissions → Metadata: Read-only.

  • Enterprise permissions → Enterprise people: Read-only. This lets Ploy surface your enterprise owners (administrators). Without it, Ploy still scans organizations normally but cannot list enterprise administrators.

  • Organization permissions → GitHub Copilot Business: Read-only. This lets Ploy show your Copilot seats as a license. Without it, Ploy skips Copilot seats and scans everything else normally.

  • Optional, for non-human identities (app installations, AI agents, deploy keys, Actions secret names and fine-grained personal access tokens): Organization permissions → Personal access tokens: Read-only and Secrets: Read-only, and Repository permissions → Administration: Read-only and Secrets: Read-only. Ploy never reads secret values.

  • Click Create GitHub App.

  • Note the App ID from the app settings page.

B. Generate a private key

  • On the app settings page, scroll to Private keys.

  • Click Generate a private key.

  • A .pem file downloads. Keep it safe.

C. Install the app

  • From the app settings page, click Install App in the sidebar.

  • Step 1: Install the app on the enterprise. This lets Ploy discover organizations.

  • Step 2: Install the same app on each GitHub organization Ploy should scan for members, repositories, and teams — including the organization you will enter as the Primary Organization in Ploy.

Common mistake: installing the app only on organizations and not on the enterprise. If setup fails, check both are installed. Ploy also checks that the app is installed on your Primary Organization, so it can run actions against it.

You can tell which level you are on from the URL:

  • Enterprise: github.com/enterprises/{slug}/settings/apps/installations

  • Organization: github.com/organizations/{org-name}/settings/installations

D. Configure in Ploy

  • Enable the GitHub Enterprise toggle.

  • Enter the GitHub Domain: github.com for Enterprise Cloud, or your self-hosted domain for GitHub Enterprise Server.

  • Enter the Enterprise Slug.

  • Select Enterprise GitHub App as the Authentication Method.

  • Paste the App ID.

  • Open the downloaded .pem file in a text editor and paste the full contents, including the BEGIN and END lines, into the Private Key field in Ploy.

  • Optional: paste a SAML token into SAML Token (optional) so Ploy can show SAML email addresses. See E below.

  • Enter your Primary Organization (required). This is the GitHub organization where Ploy will create users, manage memberships, and run other actions. Ploy will still scan members, teams, and repositories across every organization in your enterprise, but actions (joiner/leaver flows) target this organization only. The app must be installed on this organization.

E. Optional: add a SAML token for SAML email addresses

If your enterprise uses SAML single sign-on, Ploy can show the email address each GitHub user has in your identity provider. GitHub only shares enterprise SAML identities with enterprise owners, so your GitHub App cannot read them. To give Ploy those email addresses, add a separate token.

This token is used only to read your enterprise's SAML identities and their email addresses. Ploy uses it for nothing else. Scans, actions and joiner/leaver flows keep running through your GitHub App.

Create the token in GitHub

  1. Sign in to GitHub as an enterprise owner.

  2. Go to Settings → Developer settings → Personal access tokens → Tokens (classic).

  3. Click Generate new token (classic) and give it a descriptive name, for example Ploy SAML.

  4. Select only the read:enterprise scope. Leave every other scope cleared, including scim:enterprise.

  5. Click Generate token and copy it.

  6. Next to the new token, click Configure SSO and authorize it, so GitHub lets it through single sign-on.

Add it in Ploy

  1. Open the GitHub integration setup with Enterprise GitHub App selected as the Authentication Method.

  2. Paste the token into the SAML Token (optional) field and save.

  3. When Ploy tests the connection, it checks that the token can read your enterprise's SAML identities.

If something goes wrong

  • The SAML token cannot read your enterprise's SAML identities: the token was not created by an enterprise owner, is missing the read:enterprise scope, or is not authorized for SSO.

  • GitHub rejected the SAML token: the token has expired or been revoked. Create a new one and paste it in.

  • If the token stops working later, the rest of the scan carries on. Only the SAML email addresses stop updating until you replace the token.

  • If you change the GitHub Domain, enter the SAML token again or clear the field.

  • To stop using the token, clear the field and save. Delete the token in GitHub afterwards.

You do not need this token with the Personal Access Token (PAT) method. That token already belongs to an enterprise owner and has the read:enterprise scope.

Associating GitHub usernames to employees

Because engineers often use personal GitHub accounts, Ploy needs to associate those accounts with employees before it can automate access changes.

1. Luna AI

Ask Luna to associate the GitHub accounts. Luna gives recommendations based on the data available in Ploy.

2. Manual association

On the Identities page, you can also associate GitHub accounts with team members manually. Ploy can then grant and revoke access automatically.

Employee onboarding

When an engineer joins, you can use a flow to add them to the company GitHub account automatically.

Ploy uses the GitHub username association to remove access automatically during offboarding.

Employee offboarding

When an employee leaves, Ploy can automatically revoke their access to the company GitHub account.

Use the GitHub integration to manage GitHub organization access in Ploy. In most cases, the integration works with existing GitHub accounts rather than creating new ones.

Integration Capabilities

What the GitHub integration can do

  • Connect GitHub to Ploy.

  • Associate an employee with their GitHub account.

  • Invite or add an existing GitHub user to your GitHub organization.

  • Remove a user from your GitHub organization during offboarding.

  • Automate those access changes through Ploy workflows.

What the GitHub integration cannot do

  • Create a brand-new GitHub user account.

  • Delete a GitHub user account.

That means adding someone to a GitHub organization is not the same as creating a GitHub account. Ploy usually manages organization membership for an existing GitHub user.

Was this helpful?
Was this helpful?