GitLab integration overview
On This Page
- Overview
- Sign up
- Trigger a pipeline in CircleCI
- Project settings
- People
- Configuration
- Triggers
- Advanced
- Project SSH keys
- Create GitLab SSH key
- Organization settings
- People
- Inviting your first team members
- Integrations (GitLab Self-managed only)
- Establish the authenticity of an SSH host
- Roles and permissions
- Organization role permissions matrix
- Project role permissions matrix
- User settings
- Account integrations
- Deprecated system environment variables
- Coming soon
- Account integrations
- Auto-cancel redundant workflows
- Passing secrets to forked pull requests
- Stop building
- SSH rerun
- Additional SSH keys only
- Free and open source setting
- Test Insights
- Next Steps
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.
Sign up
GitLab support is open to both new and existing users of CircleCI. Follow the steps on the Sign up and try CircleCI page to connect your GitLab account to create your organization.
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 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 that demonstrate different types of workflows. The Configuring CircleCI page is a full reference to the keys used in a .circleci/config.yml file. |
When you connect a repo with your CircleCI 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.
The following limits are currently in place for GitLab integrations:
-
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.
Trigger a pipeline in CircleCI
Each time you push changes to your GitLab repository, a new pipeline is triggered and you should see it running for the project within the CircleCI web app.

Editing an existing CircleCI configuration within the web app is not currently available. You may make further changes to the config in your GitLab repo.
Committing further changes in your repo will automatically trigger a pipeline. However, manually triggering a pipeline from the CircleCI web app is also not available at this time.
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.
People
Project roles give 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. The access options are:
-
Admin: Read and write access to the project and all settings and ability to manage other users' access.
-
Contributor: Read and write access to the project and some settings.
-
Viewer: Read only access to the project and some settings.
For a complete list of permissions, see the Roles and permissions section.

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.
For GitLab Self-managed, you are able to select any instance that you have previously added as a configuration source. If you wish to set a different feature branch or repository from a self-managed instance as a new configuration source, you will first need to add a new connection via your Organization Settings. In either case, you will also need to enter your personal access token again to authorize this connection.
Once you define a configuration source, you can set up a trigger that points to that configuration.

Triggers
The scheduled pipelines feature is not currently available for use with GitLab. GitLab triggers are described below, including how to use filters to trigger pipelines based on certain conditions.
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 custom filter option. For example, a custom filter would allow you to only build on a specific branch or user.

Currently, the only fields that can be edited for existing filters are Trigger Name and the Filters radio buttons. |
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
orcancel
jobs and workflows page for more details.
Project 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.
Create GitLab SSH key
-
Create an SSH key-pair by following the GitLab instructions. When prompted to enter a passphrase, do not enter one (below is one example command to generate a key on macOS):
ssh-keygen -t ed25519 -C "your_email@example.com"
-
Go to your project on GitLab and navigate to Settings > Repository, and expand the Deploy keys section. Enter a title in the "Title" field, then copy and paste the public key you created in step 1. Check Grant write permissions to this key box, then click Add key.
-
Go to your project settings in the CircleCI app, select SSH Keys, and Add SSH key. In the "Hostname" field, enter
gitlab.com
and add the private key you created in step 1. Then click Add SSH Key. -
In your
.circleci/config.yml
file, add the fingerprint to a job using theadd_ssh_keys
key:version: 2.1 jobs: deploy-job: steps: - add_ssh_keys: fingerprints: - "SO:ME:FIN:G:ER:PR:IN:T"
When you push to your GitLab repository from a job, CircleCI will use the SSH key you added.
For more information on SSH keys, please visit the Adding an SSH key to CircleCI page.
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.
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.

-
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, refer to the Roles and permissions 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.
Integrations (GitLab Self-managed only)
For GitLab Self-managed organizations, you may connect additional self-managed instances to be integrated with your organization.
-
Navigate to Integrations within Organization Settings to add a new instance.
-
You will need to enter the instance URL, as described in the Sign up section above.
The ability to edit or delete existing integrations is not currently supported. |
For GitLab.com, account integrations can be managed under your user settings.
Establish the authenticity of an SSH host
For GitLab self-managed instances, it is necessary to add the SSH host keys to a "known hosts" file (~/.ssh/known_hosts
) so that CircleCI can verify that the host it is connecting to is authentic. The known_hosts input stores your instance’s public host keys so CircleCI jobs can verify the remote host’s identity when checking out code.
SSH keys for remote servers can be fetched by running ssh-keyscan <host>
, for example, ssh-keyscan test-gitlab.circleci.com
.
When retrieving the host keys, you can confirm that you have the correct key by checking its fingerprints. You can check the fingerprints found in the Instance Configuration section of your self-managed instance’s Help pages ( this Instance Configuration page shows an example).
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.
Organization role permissions matrix
ACTIONS | ORGANIZATION ROLES | ||
---|---|---|---|
Admin | Contributor | Viewer | |
Organization | |||
Create namespace | |||
Manage namespace | |||
View org settings | |||
Manage org settings | |||
View org access | |||
Manage org access | |||
View org credentials | |||
View org policies | |||
Manage org policies | |||
View org connections | |||
Manage org connections | |||
View org releases | |||
Manage org credentials | |||
View org audit logs | |||
View plan | |||
Manage plan | |||
Insights | |||
View org insights | |||
Runner | |||
View runners | |||
Manage runners | |||
Projects | |||
View projects | |||
Create projects | |||
Manage project settings | |||
Restore project version | |||
Delete project canary | |||
Contexts | |||
View contexts | |||
Use contexts | |||
Edit context variables | |||
Manage contexts | |||
Orbs | |||
Create/update orb | |||
View private orb | |||
Publish dev orb | |||
Publish orb | |||
Webhooks | |||
View org webhooks | |||
Manage org webhooks | |||
View project webhooks | |||
Manage project webhooks | |||
Schedule | |||
View schedule | |||
Edit schedule | |||
Triggers | |||
View triggers | |||
Trigger build | |||
Edit triggers | |||
Config sources | |||
View config sources | |||
Edit config sources |
Project role permissions matrix
ACTIONS | PROJECT ROLES | ||
---|---|---|---|
Admin | Contributor | Viewer | |
Projects | |||
View projects | |||
View project access | |||
View project credentials | |||
Restore project version | |||
Delete project canary | |||
Manage project | |||
Webhooks | |||
View project webhooks | |||
Manage project webhooks | |||
Schedule | |||
View schedule | |||
Edit schedule | |||
Triggers | |||
View triggers | |||
Trigger build | |||
Edit triggers | |||
Config sources | |||
View config sources | |||
Edit config sources |
User settings
Account integrations
In the User Settings section of your CircleCI user profile, you have the ability to enable multiple account integrations.

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
Deprecated system environment variables
There are a number of built-in environment variables that are not available in GitLab-based projects. VCS support for each environment variable is indicated in the Built-in environment variables table on the Project values and variables page. If your pipelines need these environment variables, we recommend you use suitable replacements from the available pipeline values.
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.
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.
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.
Test Insights
Test Insights is currently not supported for GitLab customers.
Next Steps
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 guide first).
- 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.