Infrastructure

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

  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.

  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 the app on the enterprise. This lets Ploy discover organizations.

  3. Step 2: Install the same app on each GitHub organization Ploy should scan for members, repositories, and teams.

Common mistake: installing the app only on organizations and not on the enterprise. If setup fails, check both are installed.

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

  1. Enable the GitHub Enterprise toggle.

  2. Enter the GitHub Domain:

    • github.com for Enterprise Cloud.

    • Your self-hosted domain for GitHub Enterprise Server.

  3. Enter the Enterprise Slug.

  4. Select Enterprise GitHub App as the authentication method.

  5. Paste the App ID.

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

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

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?