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.

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.

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

• Go to GitHub → Settings → Developer 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.

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

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

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.