Infrastructure

GitHub

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

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

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

  3. Choose which repositories to grant access to.

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

  5. 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.

2. Enterprise — Personal Access Token (PAT)

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

Setup steps

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

  2. Click Generate new token (classic).

  3. Set a descriptive name, for example Ploy Integration.

  4. Select these scopes:

    • read:enterprise

    • read:org

    • repo

  5. Click Generate token and copy it.

  6. In Ploy, enable the GitHub Enterprise toggle.

  7. Enter your GitHub Domain:

    • github.com for Enterprise Cloud.

    • Your self-hosted domain for GHES, for example github.mycompany.com.

  8. Enter your Enterprise Slug from the URL, for example github.com/enterprises/your-slug.

  9. Select Personal Access Token (PAT) as the auth method.

  10. Paste the token.

The PAT must belong to an enterprise owner.

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

  1. Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App.

  2. Configure the app:

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

    • Homepage URL: your company URL.

    • Webhook: clear Active. This is not needed.

  3. Set these permissions:

    • Organization permissions:

      • Members: Read & Write.

      • Administration: Read-only.

    • Enterprise permissions:

      • Enterprise organizations: Read & Write.

      • Enterprise single sign-on: Read-only.

    • Repository permissions:

      • Metadata: Read-only.

  4. Click Create GitHub App.

  5. Note the App ID from the app settings page.

B. Generate a private key

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

  2. Click Generate a private key.

  3. A .pem file downloads. Keep it safe.

C. Install the app

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

  2. Step 1: Install on your enterprise

    Go to your GitHub Enterprise settings and install the app on the enterprise itself, not just individual organizations. Ploy needs this to discover your organizations.

  3. Step 2: Install on each organization

    Then install the same app on each GitHub organization you want Ploy to scan. Ploy needs this to read members, repositories, and teams.

Common mistake: Installing the app only on your organizations and not on the enterprise. If setup fails, check that the app is installed at both levels.

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

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

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

D. Configure in Ploy

  1. Enable the GitHub Enterprise toggle.

  2. Enter your GitHub Domain:

    • github.com for Enterprise Cloud.

    • Your self-hosted domain for GitHub Enterprise Server.

  3. Enter your Enterprise Slug.

  4. Select Enterprise GitHub App as the auth method.

  5. Paste the App ID.

  6. Paste the full contents of the Private Key .pem file, including the BEGIN and END lines.

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 GitHub accounts with employees. She recommends matches 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 like the one below 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.

Was this helpful?