Connect & Integrate GitLab

Last updated: May 13, 2026

Introduction

This guide covers using YeshID's GitLab integration to connect your GitLab group.

Once connected, YeshID imports:

  • Users and group/project memberships

  • Groups and subgroups

  • Projects

  • Service accounts and service account tokens

  • Cluster agents and agent tokens

  • Group and project access tokens

  • Group and project deploy tokens

  • Deploy keys

  • Pipeline triggers

  • CI/CD variables (group- and project-scoped)

YeshID can also create users (by inviting them to groups at a default or mapped access level) and deactivate users (by removing their group/project memberships).

GitLab.com and self-managed GitLab are both supported.

Steps

  1. Sign in to GitLab Sign in to https://gitlab.com (or your self-managed GitLab instance) as a user that owns the top-level group you want YeshID to manage.

  2. Decide which group YeshID will manage Pick the top-level group that YeshID should review. YeshID recursively imports all subgroups, projects, members, service accounts, and tokens beneath this group.

    Note the group's:

    • Group ID (numeric, shown on the group's overview page), or

    • Full path (e.g. my-org or my-org/engineering)

  3. Create an OAuth application in GitLab Go to User Settings → Applications (for a user-owned app) or Admin Area → Applications (instance-wide).

    Click Add new application and fill in:

    • Name: YeshID

    • Redirect URI: https://app.yeshid.com/api/v1/applications/oauth/response

    • Confidential: checked

    • Scopes: api

    Save the application and copy the Application ID and Secret.

  4. Connect the integration in YeshID In YeshID, open the GitLab integration and enter:

    • Instance URL — https://gitlab.com for GitLab SaaS, or your self-managed root URL (no /api/v4 suffix)

    • Client ID — the GitLab Application ID from step 3

    • Client Secret — the GitLab Secret from step 3

    • Root Group — the group ID or full path from step 2

    • Default Access Level (optional) — role granted when YeshID adds a user to a group without an explicit role mapping. Defaults to Guest. Options: Minimal access, Guest, Planner, Reporter, Developer, Maintainer, Owner.

    For self-managed GitLab, also override the OAuth endpoints:

    • OAuth Authorize URL — <your-instance>/oauth/authorize

    • OAuth Token URL — <your-instance>/oauth/token

  5. Authorize Hit Connect. You'll be redirected to GitLab to authorize the OAuth app. Approve with the same account that owns the root group.

  6. Run a sync Start an Import Users and Import Resources sync. YeshID pulls the group tree, memberships, projects, service accounts, tokens, and CI/CD variables under your root group.

FAQ

What permissions does the authorizing user need?

The account that approves the OAuth app must have at least Maintainer on the root group to see members and projects, and Owner to see access tokens, service accounts, deploy keys, and CI/CD variables. Owner is recommended.

Why is the api scope required?

It's the only scope GitLab provides that allows reading members, projects, service accounts, tokens, and CI/CD variables together. Narrower scopes like read_api or read_user don't return the resources YeshID needs for access reviews.

Should I use a real user or a service account?

A dedicated GitLab service account or bot user is recommended. It keeps the integration working when a real user leaves and isolates the scope of access. Add it as an Owner of the root group.

Do I include /api/v4 in the Instance URL?

No. Enter just the root URL (e.g. https://gitlab.mycompany.com). YeshID appends /api/v4 automatically. If you accidentally include it, YeshID strips it.

Why are some resources missing after a sync?

If the authorizing identity doesn't have visibility into a subgroup or project, YeshID skips it rather than failing the whole import. Re-authorize with an account that has Owner on the root group to surface everything.

Does this integration support GitLab Dedicated or self-managed GitLab?

Yes. Enter your instance's root URL as Instance URL and override the OAuth Authorize / Token URLs to point at your instance.

What happens if my sync hits a rate limit?

YeshID automatically backs off and retries on GitLab 429 responses, honoring Retry-After when GitLab provides it. Large imports may take a little longer near GitLab's per-user limits, but they will complete.