GitLab SaaS integration

Cloud

Overview

This document walks you through integrating a GitLab project with CircleCI. The sections below will introduce you to new concepts and ways to manage your CI/CD pipelines. We also outline what we are working on for future releases.

GitLab support is open to both new and existing users of CircleCI. See the following two sections for directions for new and existing users.

The following limits are currently in place:

Each user can create up to three organizations.
Each organization under a Free plan can have up to 10 projects.

If you need more organizations or projects, consider upgrading to a Paid plan, or contact our Support team.

2. Create a new project

You will need API access and write permissions on the repository you want to set up. Within GitLab, this is the “maintainer” role or higher.

If you use an access token as described in the steps below, you need to select the api and write_permissions scopes.

In the CircleCI web app, navigate to Projects, then click the Create Project button.
Enter a name for your project.
Under Code Source, you have the option to connect to GitLab via OAuth, or using an access token. You must choose one.

At this time, GitLab users on the Free tier can only use personal access tokens when setting up projects in CircleCI. See Coming soon below for more details.

To connect to GitLab via OAuth: click the Connect button. A browser window will open and direct you to GitLab’s sign-in page. Once you have authenticated in GitLab, you will be redirected back to the Create New Project window in CircleCI.

It may take a second OAuth attempt to successfully connnect.

You have successfully connected to GitLab if there is a green checkmark and a note that says "CircleCI will listen to your code source for changes." You should also see a dropdown list of your GitLab repositories.

To connect using an access token: enter the access token in the field, and click the Connect button. You can use either a personal access token, or a project access token. Note that project access tokens are only available for certain GitLab subscriptions or license tiers. For more information, refer to the Personal Access Tokens and Project Access Tokens documentation on GitLab.

You have successfully connected to GitLab if you see the "Access token successful" note. You should also see a dropdown list of your GitLab repositories. The repositories available to set up will depend on what is associated with the personal or project access token you use.
Select the repository you wish to set up, then click Create Project.

Behind the scenes, CircleCI is registering a webhook within your GitLab repository. You may verify this once you have successfully created the project by navigating to your repository’s Settings > Webhooks page.

3. Trigger a project pipeline in CircleCI

At this time, setting up a new GitLab project does not automatically trigger a pipeline. Adding or editing a CircleCI configuration within the CircleCI web app is also not currently available.

If you have not already done so, create a .circleci directory at the root of your GitLab repository, and add a config.yml file in that directory.

If you are new to CircleCI, you may wish to get started with our Hello World example, or take a look at some of our sample configurations. The Configuring CircleCI document is a full reference to the keys used in a .circleci/config.yml file.

Push changes to your GitLab repository. You should see a pipeline running for the project within the CircleCI web app.

Project settings

Unlike GitHub or Bitbucket projects, the GitLab integration introduces the concept of "standalone" projects that are not specific to a VCS.

A project can have one or more configurations which are pipeline definitions, including, but not limited to, a .circleci/config.yml file in your repo.

A project can have one or more triggers, which are events from a source of change, including, but not limited to, a VCS. A trigger determines which configuration it should use to start a pipeline.

The following settings are found by clicking the Project Settings button within your project. At this time, both configurations and triggers are limited to GitLab. To read more about other settings you can enable for your projects, refer to the Settings document.

Project settings in active development

Configuration

Currently, you can add or delete a configuration source for your project. If you followed the steps above to connect GitLab, a GitLab configuration source has been automatically added for you. Once you define a configuration source, you can set up a trigger that points to that configuration.

Triggers

Add a trigger that specifies which configuration source starts a pipeline. If you followed the steps above to connect GitLab, a trigger set with GitLab as the configuration source has been automatically added for you.

Triggers and trigger rules determine how CircleCI handles events from the source of change, in this case, GitLab.

When a trigger is created, CircleCI registers a webhook with GitLab. Push events from GitLab are sent to CircleCI. CircleCI then uses the event data to determine if a pipeline should run, and if so, which pipeline should be run.

In addition to a configuration source, each trigger includes the webhook URL, and in this scenario, a CircleCI-created GitLab token. The webhook URL and GitLab token are used to securely register the webhook within GitLab in order to receive push events from your GitLab repo.

Trigger filters allow you to determine when a trigger should initiate a build based on the parameters provided by Gitlab’s webhook. CircleCI provides some common options, for example, only build on merge requests, but you can also build your own rules using the customer filter option. For example, a custom filter would allow you to only build on a specific branch or user.

Please also note the differences in functionality with the project settings below for GitLab support.

Advanced

You can enable dynamic configuration using setup workflows in CircleCI. To learn about dynamic configuration, read the Dynamic Configuration guide.
At this time, the Free and Open Source setting is not currently supported, but there are plans to make this available in the future.
At this time, auto-cancel redundant workflows is not supported. Refer to the Auto cancelling section of the Skip or cancel jobs and workflows document for more details.

SSH Keys

When creating a project, an SSH key is created which is used to checkout code from your repo. Each configuration you create generates a new SSH key to access the code in the repo associated with that configuration. At this time, only Additional SSH Keys are applicable to GitLab projects. For more information on SSH keys, please visit the Adding an SSH Key to CircleCI document.

Organization settings

The GitLab integration also introduces the concept of "standalone" organizations, which are not tied to a VCS.

A standalone organization allows for managing users and projects independent of the VCS. Organizations as well as users are considered CircleCI organizations and users, with their own roles and permissions that do not rely on those defined in a VCS.

To manage settings on the organization level, click the Organization Settings button within the CircleCI web app. More general information on organization settings in CircleCI can be found in the Settings document.

People

Add or remove users, and manage user roles for the organization as well as user invites.

You must have at least one org administrator. If you try to remove the last org administrator, you will get an error.

Inviting your first team members

Upon creating a new organization, you also have the option to invite team members from the dashboard. Alternatively, you may invite team members from the People section within Organization Settings.

People section under Organization Settings

Click the Invite button.
Enter the email address of the user you wish to invite, and select the appropriate role. You may enter multiple addresses at once, if you wish to assign these users the same role.

Organization administrator as well as organization contributor roles are currently available. Project-specific roles will be coming soon. For more information on roles and permissions, refer to the next section.
An invited user will receive an email notification (sent from noreply@circleci.com), containing a link to accept the invite.

If they do not currently have a CircleCI account, they will need to sign up. If they already have a CircleCI account, they are added to the organization, and if they are logged in, they will see the organization as an option in the organization switcher in the top left corner of the web app.

About roles and permissions

CircleCI users have different abilities depending on assigned roles in a particular organization.

Your CircleCI user roles and permissions are not derived from your VCS permissions, and they do not allow you to bypass permissions in the VCS. For example, you may be an Organization Administrator within CircleCI, which gives you access to view and modify organization and project settings within your CircleCI organization. However, you will not be able to edit a project’s .circleci/config.yml hosted in your VCS without your user also having the write permissions within that VCS’s repository project. Your CircleCI user’s VCS permissions are determined by its associated GitLab identity.

At this time, your GitLab identity can be managed through your CircleCI connection when managing triggers and configuration.

Permissions Matrix

ACTIONS	ORGANIZATION ROLES
	Admin	Contributor	Viewer
Organization
Manage org settings
View org settings
Manage plan
View plan
Insights
View org insights
Runner
Manage runners
View runners
Projects
Manage project settings
View projects
Contexts
Manage contexts
View contexts
Use contexts
Orbs
Manage namespace
Update orb categorizations
Create/update orb
Publish orb
Publish dev orb
View private orb

User settings

Account integrations

In the User Settings section of your CircleCI user profile, you have the ability to enable multiple account integrations.

When you have connected a GitLab account, clicking Connect for an additional account integration (e.g. GitHub, Bitbucket) will display the following modal:

Once you click Connect in the modal, your CircleCI accounts are merged. You will be disconnected from previously connected GitLab (i.e. standalone) organizations and will need to rejoin them. The disconnection ensures the security of your GitLab organizations as well as your other account integrations.

To rejoin those organizations, you will need to be re-invited through the process as described earlier in the Inviting your first team members section.

The ability to connect to multiple account integrations on CircleCI allows you to:

Easily access all source controls on your account
Use all authentication methods available on CircleCI

Pipeline values

GitLab-based triggers provide access to additional pipeline values. For more information on using pipeline values and parameters in CircleCI, refer to the Pipeline Values and Parameters document.

Name	Description
`pipeline.trigger_parameters.circleci.trigger_id`	ID of the trigger that received the event
`pipeline.trigger_parameters.circleci.config_source_id`	ID for the configuration source
`pipeline.trigger_parameters.circleci.trigger_type`	GitLab
`pipeline.trigger_parameters.circleci.event_time`	Timestamp CircleCI received the event
`pipeline.trigger_parameters.circleci.event_type`	Push, pull request, manual, etc.
`pipeline.trigger_parameters.circleci.project_id`	CircleCI project ID
`pipeline.trigger_parameters.circleci.actor_id`	CircleCI user ID
`pipeline.trigger_parameters.gitlab.type`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.project_id`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.ref`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.checkout_sha`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.user_id`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.user_name`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.user_username`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.user_avatar`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.repo_name`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.repo_url`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.web_url`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.commit_sha`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.commit_title`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.commit_message`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.commit_timestamp`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.commit_author_name`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.commit_author_email`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.total_commits_count`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.branch`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.default_branch`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.x_gitlab_event_id`	See Gitlab documentation for webhooks and webhook events.
`pipeline.trigger_parameters.gitlab.is_fork_merge_request`	See Gitlab documentation for webhooks and webhook events.

Deprecated system environment variables

GitLab-based projects do not have the following system environment variables available. If your pipelines need these environment variables, we recommend you use suitable replacements from the available pipeline values.

Name	Description
`CI_PULL_REQUESTS`	Comma-separated list of URLs of the current build’s associated pull requests.
`CI_PULL_REQUEST`	The URL of the associated pull request. If there are multiple associated pull requests, one URL is randomly chosen.
`CIRCLE_PR_NUMBER`	The number of the associated GitHub or Bitbucket pull request. Only available on forked PRs.
`CIRCLE_PR_USERNAME`	The GitHub or Bitbucket username of the user who created the pull request. Only available on forked PRs.
`CIRCLE_PR_REPONAME`	The name of the GitHub or Bitbucket repository where the pull request was created. Only available on forked PRs.
`CIRCLE_PROJECT_USERNAME`	The GitHub or Bitbucket username of the current project.
`CIRCLE_PROJECT_REPONAME`	The name of the repository of the current project.
`CIRCLE_REPOSITORY_URL`	The URL of your GitHub or Bitbucket repository.
`CIRLCE_SHA1`	The SHA1 hash of the last commit of the current build.
`CIRCLE_TAG`	The name of the git tag, if the current build is tagged. For more information, see the Git Tag Job Execution section of the Using Workflows to Schedule Jobs document.

If you must use these as environment variables in your pipelines, you can do so by using the environment key in your configuration and providing your own mappings:

build:
  docker:
    - image: cimg/node:17.0
  environment:
    CIRCLE_PROJECT_REPONAME: << pipeline.trigger_parameters.gitlab.repo_name >>
  steps:
    - run: echo $CIRCLE_PROJECT_REPONAME

Coming soon

The following sections are features of CircleCI which are not currently fully supported for GitLab. These features are planned for future releases.

Account integrations

There is currently no method to manage the connection with GitLab outside of the project setup, trigger, and configuration settings. CircleCI is working on enabling users to manage their users’ GitLab identity as part of their user profile’s account integration settings.

Project roles

Provider roles give even greater control over which users have access to which projects within an organization. This enables teams to have limited access to only their projects, while managers and others can have broader organizational access.

Auto-cancel redundant workflows

Auto-cancel redundant workflows is not currently supported. It is often used to remove noise from the pipeline page and lower the time to feedback for a commit. Refer to the Skip or cancel jobs and workflows page for more details.

Restricted access to contexts

Restricted access to contexts is not currently supported. Any users that can trigger pipelines from the source can use contexts. We will be offering multiple methods to restrict contexts in the future.

If you would like more information about using contexts within CircleCI, visit the Using contexts page.

Passing secrets to forked pull requests

Passing secrets to forked pull requests is not a currently supported option for GitLab integrations.

Stop building

GitLab integrations do not currently support the Stop Building option that can normally be found in Project settings. The recommendation is to delete your webhooks in your GitLab repo if you no longer want a CircleCI pipeline to run.

SSH rerun

Support for SSH rerun will only work if your user account has a Bitbucket or GitHub integration in addition to GitLab. Your user account’s Bitbucket or GitHub SSH keys can be used for SSH reruns with GitLab. CircleCI will be adding functionality to allow users to manage SSH keys so SSH reruns are possible. SSH reruns do not get passed context secrets. CircleCI is working on providing administrators with greater control over the use of secrets and SSH reruns.

Additional SSH keys only

Deploy keys and user keys are not used by GitLab integrations. GitLab keys are stored in Project Settings > Additional SSH Keys. However, CircleCI does not recommend manually managing your SSH keys for code checkout. Instead, use the Set Up Project option, or Project Settings > Configuration, to maintain connections to your repository.

Free and open source setting

Open source plans are not currently available to GitLab customers. CircleCI will keep the open source community up to date as work continues to support this.

Plan pages UI

The plan pages currently display the organization UUID instead of the organization name in the top left corner when viewing the Plan section.

GitLab free plans

If your GitLab account supports it, CircleCI will create a GitLab project token whenever possible when setting up a project. If you are on a Free GitLab plan it is not possible to create a project token, so CircleCI will require and use a personal API token. Please note, if you are on a paid plan and enter a personal API token during project setup, CircleCI will use your personal API token to create a project token.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Suggest an edit to this page (please read the contributing guidefirst).
To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

GitLab SaaS integration

On This Page

Overview

1. Sign up

2. Create a new project

3. Trigger a project pipeline in CircleCI

Project settings

Project settings in active development

Configuration

Triggers

Advanced

SSH Keys

Organization settings

People

Inviting your first team members

About roles and permissions

Permissions Matrix

User settings

Account integrations

Pipeline values

Deprecated system environment variables

Coming soon

Account integrations

Project roles

Auto-cancel redundant workflows

Restricted access to contexts

Passing secrets to forked pull requests

Stop building

SSH rerun

Additional SSH keys only

Free and open source setting

Plan pages UI

GitLab free plans

Help make this document better

Need support?