Start Building for Free

GitLab Support Preview Documentation

6 days ago10 min read
On This Page


This document walks you through integrating a GitLab project with CircleCI. It introduces you to new concepts and ways to manage your CI/CD pipelines. In this document, we also outline some known issues as well as what we are working on for future releases.

Step one - Sign up

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

New CircleCI users: Create a CircleCI account and create your first organization

  1. Sign up for CircleCI using the Sign up with Email option (you will also create a password).

  2. After you set an email and password, you will be taken to a screen with the option to connect GitLab, GitHub, or Bitbucket. Click Connect for GitLab.

  3. The next page should include a "Welcome to the GitLab VCS Support Preview" message. You will be prompted to create a new organization. Enter an organization name and click Create Organization.

    Create new organization

After you successfully create a new organization, you will be taken to the web app dashboard. Follow the steps in Step Two below to create a new project.

Current CircleCI users: Create a new organization

  1. Log in to the CircleCI web app.

  2. Click on your organization name to open the organization switcher on the top left. Select Create New Organization.

  3. The next page should include a "Welcome to the GitLab VCS Support Preview" message. Enter a unique name for your new organization.

  4. Click Create Organization.

This new organization allows you to manage users and GitLab projects within the organization. The organization will be under its own Free plan to start. You can upgrade to another plan later. This pricing plan is independent of any GitHub or Bitbucket organizations you have previously set up with your account.

Once you successfully create a new organization, you will be taken to the organization dashboard. Follow the steps in Step Two below to set up a new GitLab project.

Step two - 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.

  1. In the CircleCI web app, navigate to Projects, then click the Create Project button.

  2. Enter a name for your project.

  3. Under Code Source, you have the option to connect to GitLab via OAuth, or using an access token. You must choose one.

    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.

    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.

    Successful GitLab connection via OAuth

    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.

    Successful GitLab connection using access token
  4. 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.

Step three - 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.

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

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

    Successful pipeline run

Project settings

Unlike GitHub or Bitbucket projects, the GitLab support preview 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


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.

Configuration setup page


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.

Trigger setup page

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 details

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.

Trigger details


  • 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 preview 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.


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

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
  1. Click the Invite button.

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

  3. An invited user will receive an email notification (sent from, 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

User access and roles within CircleCI are independent of roles within GitLab. Each user can have one organization role: either an admin, contributor, or viewer.

Contributors cannot edit organization settings such as contexts or plans, nor can they invite users. Org contributors can, however, view contexts, and create and view projects Administrators are able to invite users and update role settings.

  • Org Administrator: For those managing CircleCI as a whole—managing users, managing plans, updating billing information, and managing contexts.

  • Org Contributor: For users that might create and administer multiple projects within CircleCI, but are not required to manage organization settings.

  • Org Viewer: For users such as those in support roles that do not contribute code but need to see reports, know the status of projects, or validate plan usage.

  • Project Administrator (coming soon): For ensuring teams only have access to individual projects and not all projects across the organization. Project administrators, typically the team manager or lead, will have access to project settings.

  • Project Contributor (coming soon): For individual team members who are not required to manage project settings.

  • Project Viewer (coming soon): For users that might need to know the status of an individual project, but are not committing changes.

Coming soon

Auto-cancel redundant workflows

Auto-cancel redundant workflows is not supported at this time. Refer to the Auto cancelling section of the Skip or cancel jobs and workflows document for more details.

Restricted access to contexts

Restricted access to contexts is not supported in the GitLab preview at this time. This means that any user within the organization can create triggers, and any users that can trigger pipelines from the source can use those contexts. In a future update, it will be possible to limit access to contexts by project and/or branch, giving your organization greater control and ensuring individual users only have access to the contexts they require.

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

Project roles

Organizations can limit user access to a project or projects, and not require an organization-level role. This gives greater control over which users have access to projects across the organization, and limits access to organization settings or creating new projects.

Account integrations

There is currently no method to manage GitLab integrations in this area. We are working on including GitLab in the options listed.

Known issues

SSH rerun is not working

Support for SSH rerun is currently not available. This will be resolved in a future release.

Additional SSH keys only

Deploy Key and User Key are not being used at this time. All SSH keys generated for a project will be stored under Additional SSH Keys.

User account integrations do not include GitLab

The User Settings > Account Integrations page does not currently include GitLab as a choice.

At this time, GitLab integration should only be configured through new project creation. Project settings for creating triggers and configuration will be added soon.

Advanced options in project settings

  • Auto-cancel redundant workflows is not currently supported.

  • The Free and Open Source setting is not currently supported.

  • Project settings for building forked pull requests are not available.

Stop building option in project settings

Stop Building does not work. The recommendation is to delete your webhooks in your GitLab repo if you no longer want a CircleCI pipeline to run.

Plans and usage

  • Plans pages display the organization UUID and not the name.

  • Usage pages do not include the GitLab project name under Projects.

  • Only users that created a project in CircleCI and triggered a build are counted as active users.

GitLab OAuth for Free plans

  • The current CircleCI OAuth connection with GitLab is not successfully refreshing the token after the two hour expiration time. Users that are on a free GitLab plan will not be able to set up additional projects and builds will fail after the two hour expiry. We are working on resolving this issue. In the meantime, users with free GitLab plans should use a personal access token when setting up a new project.

  • For users on the free GitLab plan that have already set up GitLab projects with OAuth in CircleCI, we recommend revoking the CircleCI application from within GitLab until this issue is resolved.

    1. You can revoke the CircleCI application by navigating to your GitLab user account’s Preferences > Applications.

    2. Next, delete your trigger and configuration from your CircleCI project via Project Settings.

    3. You can then manually add a new configuration and trigger using a personal access token. Note that the "GitLab X Token" is a secret and can be anything you want.

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.

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.