Infrastructure

GitLab Integration

Ploy connects to GitLab to scan your groups and their members, so you can see who has access to GitLab and at what role. Ploy never reads your source code, merge requests, or issues.

You can connect GitLab in one of two ways. Choose the one that fits your security requirements — both scan exactly the same data (groups, members, roles, and last-activity). The only difference is how Ploy authenticates and what the connection is technically permitted to access.

OAuth vs personal access token: which should I choose?

OAuth (recommended) is the quickest way to connect. You create a GitLab OAuth application and Ploy walks you through a one-click authorization. GitLab's OAuth only offers a single broad read scope (read_api), which technically permits reading repository contents. Ploy never does this — it only reads group membership — but the permission is granted to the connection.

Personal access token lets you create a fine-grained, read-only token yourself and grant it only the permissions Ploy needs. Choose this if your organization requires a guarantee that Ploy is structurally unable to read your source code: a token granted no repository permission simply cannot read code.

First, create a GitLab OAuth application:

  1. In GitLab, open your group or user Settings, then Applications.

  2. Click Add new application.

  3. Give it a name, for example Ploy.

  4. Set the Redirect URI to the value shown in the Ploy setup screen.

  5. Under Scopes, select read_api.

  6. Click Save application, then copy the Application ID and Secret.

Then, in Ploy:

  1. Open the GitLab integration setup and choose OAuth (recommended).

  2. Paste the Application ID and Secret, then save.

  3. Click Grant access and authorize Ploy on the GitLab screen.

Option 2: Connect with a personal access token (no code access)

Create a fine-grained personal access token in GitLab:

  1. In GitLab, open Settings, then Access tokens, then Personal access tokens.

  2. From the Generate token dropdown, select Fine-grained token.

  3. Give it a name, for example Ploy, and an expiry date.

  4. Under Group and project access, select the groups you want Ploy to scan, or all groups you are a member of.

  5. Under Add resource permissions, grant only the four read permissions listed below, and nothing else.

  6. Click Generate token and copy it.

Grant exactly these permissions, each set to Read:

  • Group and project, then Member

  • Group and project, then Group

  • User, then User

  • User, then Group

Do not grant any Repository or Project permission. Leaving those unselected is what guarantees Ploy cannot read your source code.

Then, in Ploy:

  1. Open the GitLab integration setup and choose Personal access token.

  2. Paste the token, then save.

Choosing which groups Ploy scans (optional)

Both connection methods share an optional Group IDs field. Leave it blank and Ploy automatically discovers and scans every group the connection can access. To limit Ploy to specific groups, enter a comma-separated list of GitLab group IDs or full paths, for example my-company, 12345. Ploy then scans only those groups and ignores all others.

What Ploy reads

With either method, Ploy reads the groups (and subgroups) the connection can access, each group's members (username, role, and join date), and last-activity data to show which members are active. Ploy never reads repository contents, merge requests, issues, or any source code.

Was this helpful?
Was this helpful?