GitLab

GitLab: Overview and setup

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

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