gitlab-plugin

GitLab Plugin

Table of Contents

• Introduction
• User support
• Known bugs/issues
• Defined variables
• Global plugin configuration
  • GitLab-to-Jenkins auth
  • Jenkins-to-GitLab auth
  • Jenkins Job Configuration
  • Parameter configuration
  • Git configuration
    • Freestyle jobs
    • Pipeline jobs
    • Pipeline Multibranch jobs
  • Job trigger configuration
    • Webhook URL
    • Freestyle and Pipeline jobs
    • Pipeline Multibranch jobs
    • Multibranch Pipeline jobs with Job DSL
  • Build status configuration
    • Freestyle jobs
    • Scripted Pipeline jobs
    • Declarative Pipeline jobs
    • Matrix jobs
  • See also
• Advanced features
  • Branch filtering
  • Build when tags are pushed
  • Add a note to merge requests
  • Accept merge request after build
  • Notify specific project by a specific GitLab connection
  • Cancel pending builds on merge request update
  • Cancel running builds on merge request update
  • Check if a label is applied to a merge request
• Compatibility
• Contributing to the Plugin
• Testing With Docker
• Release Workflow
• Changelog

Introduction

This plugin allows GitLab to trigger builds in Jenkins when code is committed or merge requests are opened/updated. It can also send build status back to GitLab.

User support

Relationship with GitLab Inc.

This plugin is Open Source Software, developed on a volunteer basis by users of Jenkins and GitLab. It is not formally supported by either GitLab Inc. or CloudBees Inc.

Supported GitLab versions

GitLab performs a new major release about every six to nine months, and they are constantly fixing bugs and adding new features. As a result, we cannot support this plugin when used with GitLab versions older than N-2, where N is the current major release.

Getting help

If you have a problem or question about using the plugin, please make sure you are using the latest version. Then create an issue in the GitHub project.

To enable debug logging in the plugin:

1. Go to Jenkins -> Manage Jenkins -> System Log
2. Add new log recorder
3. Enter 'GitLab plugin' or whatever you want for the name
4. On the next page, enter 'com.dabsquared.gitlabjenkins' for Logger, set log level to FINEST, and save
5. Then click on your GitLab plugin log, click 'Clear this log' if necessary, and then use GitLab to trigger some actions
6. Refresh the log page and you should see output

Known bugs/issues

The plugin tracks current issues with the GitHub issue tracker. Some issues are reported in the Jenkins Jira issue tracker. When searching for existng issues, please check both locations.

Report an Issue

Please report issues and enhancements through the GitHub issue tracker.

Defined variables

When GitLab triggers a build via the plugin, various environment variables are set based on the JSON payload that GitLab sends. You can use these throughout your job configuration. The available variables are:

…

NOTE: These variables are not available in Pipeline Multibranch jobs.

Global plugin configuration

GitLab-to-Jenkins authentication

The plugin requires authentication to connect from GitLab to Jenkins. This prevents unauthorized persons from triggering jobs.

Authentication Security

APITOKENS and other secrets MUST not be send over unsecure connections. So, all connections SHOULD use HTTPS.

Note: Certificates are free and easy to manage with LetsEncrypt.

Configuring global authentication

1. Create a user in Jenkins which has, at a minimum, Job/Build permissions
2. Log in as that user (this is required even if you are a Jenkins admin user), then click on the user's name in the top right corner of the page
3. Click 'Configure,' then 'Add new Token', and note/copy the User ID and API Token
4. In GitLab, when you create webhooks to trigger Jenkins jobs, use this format for the URL and do not enter anything for 'Secret Token': https://USERID:APITOKEN@JENKINS_URL/project/YOUR_JOB
5. After you add the webhook, click the 'Test' button, and it should succeed

Configuring per-project authentication

If you want to create separate authentication credentials for each Jenkins job:

1. In the configuration of your Jenkins job, in the GitLab configuration section, click 'Advanced'
2. Click the 'Generate' button under the 'Secret Token' field
3. Copy the resulting token, and save the job configuration
4. In GitLab, create a webhook for your project, enter the trigger URL (e.g. https://JENKINS_URL/project/YOUR_JOB) and paste the token in the Secret Token field
5. After you add the webhook, click the 'Test' button, and it should succeed

Disabling authentication

If you want to disable this authentication (not recommended):

1. In Jenkins, go to Manage Jenkins -> Configure System
2. Scroll down to the section labeled 'GitLab'
3. Uncheck "Enable authentication for '/project' end-point" - you will now be able to trigger Jenkins jobs from GitLab without needing authentication

Jenkins-to-GitLab authentication

PLEASE NOTE: This auth configuration is only used for accessing the GitLab API for sending build status to GitLab. It is not used for cloning git repos. The credentials for cloning (usually SSH credentials) should be configured separately, in the git plugin.

This plugin can be configured to send build status messages to GitLab, which show up in the GitLab Merge Request UI. To enable this functionality:

1. Create a new user in GitLab
2. Give this user 'Maintainer' permissions on each repo you want Jenkins to send build status to
3. Log in or 'Impersonate' that user in GitLab, click the user's icon/avatar and choose Settings
4. Click on 'Access Tokens'
5. Create a token named e.g. 'jenkins', with scope set to 'api' and role set to 'Developer' (for protected branches, a higher role might be needed. See Roles and permissions on GitLab). Setting expiration is optional.
6. Copy the token immediately, it cannot be accessed after you leave this page
7. On the Global Configuration page in Jenkins, in the GitLab configuration section, supply the GitLab host URL, e.g. https://your.gitlab.server
8. Click the 'Add' button to add a credential, choose 'GitLab API token' as the kind of credential, and paste your GitLab user's API key into the 'API token' field
9. Click the 'Test Connection' button; it should succeed

Jenkins Job Configuration

There are two aspects of your Jenkins job that you may want to modify when using GitLab to trigger jobs. The first is the Git configuration, where Jenkins clones your git repo. The GitLab Plugin will set some environment variables when GitLab triggers a build, and you can use those to control what code is cloned from Git. The second is the configuration for sending the build status back to GitLab, where it will be visible in the commit and/or merge request UI.

Parameter configuration

If you want to be able to run jobs both manually and automatically via GitLab webhooks, you will need to configure parameters for those jobs. If you only want to trigger jobs from GitLab, you can skip this section.

Any GitLab parameters you create will always take precedence over the values that are sent by the webhook, unless you use the EnvInject plugin to map the webhook values onto the job parameters. This is due to changes that were made to address security vulnerabilities, with changes that landed in Jenkins 2.3.

In your job configuration, click 'This build is parameterized' and add any parameters you want to use. See the defined variables list for options - your parameter names must match these .e.g sourceBranch and targetBranch in the example Groovy Script below. Then, having installed EnvInject, click 'Prepare an environment for the run' and check:

• Keep Jenkins Environment Variables
• Keep Jenkins Build Variables
• Override Build Parameters

In the Groovy Script field insert something similar to:

def env = currentBuild.getEnvironment(currentListener)
def map = [:]

if (env.gitlabSourceBranch != null) {
  map['sourceBranch'] = env.gitlabSourceBranch
}

if (env.gitlabTargetBranch != null) {
  map['targetBranch'] = env.gitlabTargetBranch
}

return map

You can then reference these variables in your job config, e.g. as ${sourceBranch}. You will need to update this code anytime you add or remove parameters.

Note: If you use the Groovy Sandbox, you might need to approve the script yourself or let an administrator approve the script in the Jenkins configuration.

Git configuration

Freestyle jobs

In the Source Code Management section:

1. Click Git
2. Enter your Repository URL, such as [email protected]:gitlab_group/gitlab_project.git
   1. In the Advanced settings, set Name to origin and Refspec to +refs/heads/*:refs/remotes/origin/* +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
3. In Branch Specifier enter:
   1. For single-repository workflows: origin/${gitlabSourceBranch}
   2. For forked repository workflows: merge-requests/${gitlabMergeRequestIid}
4. In Additional Behaviours:
   1. Click the Add drop-down button
   2. Select Merge before build from the drop-down
   3. Set Name of repository to origin
   4. Set Branch to merge as ${gitlabTargetBranch}

Pipeline jobs

• A Jenkins Pipeline bug will prevent the Git clone from working when you use a Pipeline script from SCM. It works if you use the Jenkins job config UI to edit the script. There is a workaround mentioned here: https://issues.jenkins-ci.org/browse/JENKINS-33719

• Use the Snippet generator, General SCM step, to generate sample Groovy code for the git checkout/merge etc.

• Example that performs merge before build:

checkout changelog: true, poll: true, scm: [
    $class: 'GitSCM',
    branches: [[name: "origin/${env.gitlabSourceBranch}"]],
    extensions: [[$class: 'PreBuildMerge', options: [fastForwardMode: 'FF', mergeRemote: 'origin', mergeStrategy: 'DEFAULT', mergeTarget: "${env.gitlabTargetBranch}"]]],
    userRemoteConfigs: [[name: 'origin', url: '[email protected]:foo/testrepo.git']]
    ]

Pipeline Multibranch jobs

Note: There is no way to pass external data from GitLab to a Pipeline Multibranch job, so the GitL