Skip to main content

GitLab: Overview and setup

Automate projects, issues, CI/CD pipelines, and group access with the GitLab integration.

R
Written by Riya Sebastian

Connect GitLab to Atomicwork to automate project management, issue tracking, CI/CD pipeline operations, and team access management as part of your IT and developer workflows.

Use cases

By connecting GitLab, your teams can:

  • Automate project management: Create and manage GitLab projects, and control team membership by adding or removing users with specific access levels (Guest, Reporter, Developer, Maintainer).

  • Streamline issue tracking: Create, update, and track GitLab issues from Atomicwork workflows — for example, automatically creating a GitLab issue when an incident is reported or a change request is approved.

  • Trigger CI/CD pipelines: Trigger and monitor GitLab pipelines as part of deployment or release workflows.

  • Manage group access: Invite users to GitLab groups with specific roles and optional access expiration, making it easy to manage access during onboarding and offboarding.

Permissions

To connect GitLab to Atomicwork, you need:

  • Org admin access in Atomicwork

  • Admin access to your GitLab instance (or GitLab.com account) with permission to create OAuth applications

The integration authenticates via OAuth 2.0 and requests the api scope, which provides full read/write access to the GitLab API. For security reviews, the table below lists the equivalent narrower scopes that describe the specific capabilities the integration uses:

OAuth Scope

Purpose

api

Full read/write access to the GitLab API. Required for all supported actions — project management, issue tracking, CI/CD pipeline operations, group access, and user management. This is the scope Atomicwork requests during authorization.

read_api

Read access to the API. Covers the List projects, Get project, List issues, Get issue, List pipelines, Get pipeline, List groups, and List users actions.

read_user

Read user profile information. Covers user lookup operations during member invites and access management.

read_repository

Read repository data. Covers project and issue retrieval operations.

write_repository

Write access to repositories. Covers Create project, Create issue, Update issue, and Trigger pipeline actions.

Note: The Atomicwork integration authorizes with the api scope, which is the GitLab umbrella scope covering all of the narrower scopes listed above. The narrower scopes are documented here so your security team can map the integration's capabilities to your access policy.

Setup

Before connecting, gather the following from your GitLab OAuth application settings:

  • Application ID (Client ID)

  • Secret (Client Secret)

For self-hosted GitLab instances, you'll also need your GitLab instance URL.

  • Navigate to Settings > App Store > GitLab.

  • Click Connect to initiate the OAuth flow.

  • Sign in with your GitLab account and authorize the requested permissions.

  • Once authorized, the integration is active.

Supported workflow actions

Once connected, you can automate the following GitLab actions within your Atomicwork workflows:

Action

Description

List projects

List GitLab projects with search and pagination.

Create project

Create a new GitLab project.

Get project

Retrieve detailed information about a specific project.

Add project member

Add a user to a project with a specific access level (Guest, Reporter, Developer, or Maintainer).

List issues

List issues in a project with search and pagination.

Create issue

Create a new issue in a project with title, description, labels, and assignee.

Get issue

Retrieve detailed information about a specific issue.

Update issue

Update an existing issue's title, description, status, assignee, or labels.

List pipelines

List CI/CD pipelines for a project.

Trigger pipeline

Trigger a CI/CD pipeline for a project.

Get pipeline

Retrieve detailed information about a specific pipeline run.

List groups

List GitLab groups with search and pagination.

Invite group member

Invite a user to a group with a specific access level and optional access expiration date.

List users

List GitLab users with search and pagination.

Call API

Make a generic API call to any GitLab endpoint for custom operations.

Troubleshoot common issues

Error

Cause

Resolution

Failed to exchange token

Token acquisition failed — the authorization code may have expired or the redirect URI doesn't match.

Verify the OAuth application configuration in GitLab and re-initiate the connection from Settings > App Store > GitLab.

Token response missing required fields

The OAuth response from GitLab is incomplete.

Check your GitLab OAuth application configuration and ensure it's properly set up.

Token refresh failure

The refresh token has expired or been revoked.

Re-authenticate the integration to generate new tokens.

Did this answer your question?