- Introduction
- User support
- Known bugs/issues
- Supported GitLab versions
- Supported GitLabCI Functions
- Configuring access to GitLab
- Branch filtering
- Build Tags
- Parameterized builds
- Contributing to the Plugin
- Quick test environment setup using Docker
- Release Workflow
This plugin allows GitLab to trigger builds in Jenkins after code is pushed and/or after a merge request is created.
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 if necessary. New issues should include the following:
- GitLab plugin version (e.g. 1.2.0)
- GitLab version (e.g. 8.1.1)
- Jenkins version (e.g. 1.651.1)
- Relevant log output from the plugin (see below for instructions on capturing this)
Version 1.2.0 of the plugin introduced improved logging for debugging purposes. To enable it:
- Go to Jenkins -> Manage Jenkins -> System Log
- Add new log recorder
- Enter 'Gitlab plugin' or whatever you want for the name
- On the next page, enter 'com.dabsquared.gitlabjenkins' for Logger, set log level to FINEST, and save
- Then click on your Gitlab plugin log, click 'Clear this log' if necessary, and then use GitLab to trigger some actions
- Refresh the log page and you should see output
You can also try chatting with us in the #gitlab-plugin channel on the Freenode IRC network.
This is not an exhaustive list of issues, but rather a place for us to note significant bugs that may impact your use of the plugin in certain circumstances. For most things, please search the Issues section and open a new one if you don't find anything.
- #272 - Plugin version 1.2.0+ does not work with GitLab Enterprise Edition < 8.8.3, due to a bug on their side.
- Jenkins versions 1.651.2 and 2.3 removed the ability of plugins to set arbitrary job parameters that are not specifically defined in each job's configuration. This was an important security update, but it has broken compatibility with some plugins, including ours. See here for more information and workarounds if you are finding parameters unset or empty that you expect to have values.
- GitLab versions 8.1.x and newer (both CE and EE editions) are supported via the GitLab commit status API which supports with external CI services like Jenkins
- Versions older than 8.1.x may work but are no longer officially supported
Optionally, the plugin communicates with the GitLab server in order to fetch additional information. At this moment, this information is limited to fetching the source project of a Merge Request, in order to support merging from forked repositories.
To enable this functionality, a user should be set up on GitLab, with GitLab 'Developer' permissions, to access the repository. You will need to give this user access to each repo you want Jenkins to be able to clone. Log in to GitLab as that user, go to its profile, and copy its secret API key. On the Global Configuration page in Jenkins, supply the GitLab host URL, e.g. http:https://your.gitlab.server.
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. Testing the connection should succeed.
- In the Source Code Management section:
- Click Git
- Enter your Repository URL, such as
[email protected]:gitlab_group/gitlab_project.git
- 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/*
- In order to merge from forked repositories:
Note: this requires configuring communication to the GitLab server
- Click Add Repository to specify the merge request source repository. Then specify:
- URL:
${gitlabSourceRepoURL}
- In the Advanced settings, set Name to
${gitlabSourceRepoName}
. Leave Refspec blank.
- URL:
- In Branch Specifier enter:
- For single-repository workflows:
origin/${gitlabSourceBranch}
- For forked repository workflows:
merge-requests/${gitlabMergeRequestIid}
- In Additional Behaviours:
- Click the Add drop-down button
- Select Merge before build from the drop-down
- Set Name of repository to
origin
- Set Branch to merge as
${gitlabTargetBranch}
Note: Since version 1.2.0 the gitlab-plugin sets the gitlab hook values through environment variables instead of build parameters. To set default values, consult EnvInject Plugin.
Incompatibility note: When upgrading to version 1.2.1 or later of the plugin, if you are using Pipeline jobs you will need to manually reconfigure your Pipeline scripts. In older versions the plugin set global Groovy variables that could be accessed as e.g. ${gitlabSourceBranch}. After version 1.2.1, these variables are only accessible in the env[] map. E.g. ${env.gitlabSourceBranch}.
-
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}"]], doGenerateSubmoduleConfigurations: false, extensions: [[$class: 'PreBuildMerge', options: [fastForwardMode: 'FF', mergeRemote: 'origin', mergeStrategy: 'default', mergeTarget: "${env.gitlabTargetBranch}"]]], submoduleCfg: [], userRemoteConfigs: [[name: 'origin', url: 'git@mygitlab:foo/testrepo.git']]]
Note: none of the GitLab environment variables are available for mulitbranch pipeline jobs as there is no way to pass some additional data to a multibranch pipeline build while notifying a multibranch pipeline job about SCM changes. Due to this the plugin just listens for GitLab Push Hooks for multibranch pipeline jobs.
- Click Add source
- Select Git
- Enter your Repository URL (e.g.:
[email protected]:group/repo_name.git
)
Example Jenkinsfile
for multibranch pipeline jobs
properties: [[$class: 'GitLabConnectionProperty', gitLabConnection: '<your-gitlab-connection-name>']]
node {
stage "checkout"
checkout scm
stage "build"
gitlabCommitStatus("build") {
// your build steps
}
stage "test"
gitlabCommitStatus("test") {
// your test steps
}
}
- In the Build Triggers section:
- Select Build when a change is pushed to GitLab
- Make a note of the GitLab CI Service URL appearing on the same line with Build when a change is pushed to GitLab. You will later use this URL to define a GitLab web hook.
- Use the check boxes to trigger builds on Push Events and/or Merge Request Events
- Optionally use Rebuild open Merge Requests to enable re-building open merge requests after a push to the source branch
- If you selected Rebuild open Merge Requests other than None, check Comments, and specify the Comment for triggering a build. A new build will be triggered when this phrase appears in a commit comment. In addition to a literal phrase, you can also specify a Java regular expression.
- Configure any other pre build, build or post build actions as necessary
- Click Save to preserve your changes in Jenkins.
The Jenkins Matrix/Multi-configuration job type is not supported.
GitLab 8.1 has implemented a commit status api, you need an extra post-build step to support commit status.
-
In GitLab go to your repository's project Settings
- Click on Web Hooks
- Earlier in Jenkins, you made a note of the GitLab CI Service URL, which is of the form
http:https://JENKINS_URL/project/JENKINS_PROJECT_NAME
. Specify this as the web hook URL. Note thatJENKINS_PROJECT_NAME
is the name of the Jenkins project you want to trigger, including Jenkins folders. - Select Merge Request Events and Push Events
- Click Add Webhook
- Click Test Hook to test your new web hook. You should see two results:
- GitLab should display "Hook successfully executed"
- Jenkins project
JENKINS_PROJECT_NAME
should start
-
Add a post-build step Publish build status to GitLab commit (GitLab 8.1+ required) to the job.
-
For pipeline jobs surround your build step with the gitlabCommitStatus step like this:
node() { stage 'Checkout' checkout <your-scm-config> gitlabCommitStatus { <script that builds, tests, etc. your project> } }
-
For pipeline jobs there is also the updateGitlabCommitStatus step to use a custom state for updating the commit status:
node() { stage 'Checkout' checkout <your-scm-config> updateGitlabCommitStatus name: 'build', state: 'pending' }
-
To mark several build stages as pending in GitLab you can use the gitlabBuilds step:
node() { stage 'Checkout' checkout <your-scm-config> gitlabBuilds(builds: ["build", "test"]) { stage "build" gitlabCommitStatus("build") { // your build steps } stage "test" gitlabCommitStatus("test") { // your test steps } } }
-
Configure access to GitLab as described above in "Configure access to GitLab" (the account needs at least developer permissions to post commit statuses)
Triggers may be filtered based on the branch name, i.e. the build will only be allowed for selected branches. On the project configuration page, when you configure the GitLab trigger, you can choose 'Filter branches by name' or 'Filter branches by regex.' Filter by name takes comma-separated lists of branch names to include and/or exclude from triggering a build. Filter by regex takes a Java regular expression to include and/or exclude.
Note: This functionality requires accessing the GitLab server (see above) and for the time being also a git repository url already saved in the project configuration. In other words, when creating a new project, the configuration needs to be saved once before being able to select the allowed branches. For Workflow/Pipeline jobs, the configuration must be saved and the job must be run once before the list is populated. For existing projects, all branches are allowed to push by default.
In order to build when a new tag is pushed:
- In the
GitLab server
addTag push events
to theWeb Hook
- In the
Jenkins
under theSource Code Management
section:- select
Advance...
and add+refs/tags/*:refs/remotes/origin/tags/*
asRefspec
- you can also use
Branch Specifier
to specify which tag need to be built (exampplerefs/tags/${TAGNAME}
)
- select
-
In the Post build steps section:
- Click Add post build step
- Click Add note with build status on GitLab merge requests and save build settings (You enabled autoumatically sending default message on result of a build)
-
If you want make custom message on result of a build:
- In Add note with build status on GitLab merge requests section click to Custom message on success/failure/abort
- Write text of message, you can use Environment variables
You can trigger a job a manually by clicking This build is parameterized
and adding the any of the relevant build parameters.
These include:
- gitlabBranch
- gitlabSourceBranch
- gitlabActionType
- gitlabUserName
- gitlabUserEmail
- gitlabSourceRepoHomepage
- gitlabSourceRepoName
- gitlabSourceNamespace
- gitlabSourceRepoURL
- gitlabSourceRepoSshUrl
- gitlabSourceRepoHttpUrl
- gitlabMergeRequestTitle
- gitlabMergeRequestDescription
- gitlabMergeRequestId
- gitlabMergeRequestIid
- gitlabMergeRequestLastCommit
- gitlabTargetBranch
- gitlabTargetRepoName
- gitlabTargetNamespace
- gitlabTargetRepoSshUrl
- gitlabTargetRepoHttpUrl
Plugin source code is hosted on Github. New feature proposals and bug fix proposals should be submitted as Github pull requests. Fork the repository on Github, prepare your change on your forked copy, and submit a pull request (see here for open pull requests). Your pull request will be evaluated by the Cloudbees Jenkins job.
If you are adding new features please make sure that they support the Jenkins Workflow Plugin. See here for some information.
Before submitting your change make sure that:
- your changes work with the oldest and latest supported GitLab version
- new features are provided with tests
- refactored code is provided with regression tests
- the code formatting follows the plugin standard
- imports are organised
- you updated the help docs
- you updated the README
- you have used findbugs to see if you haven't introduced any new warnings.
In order to test the plugin on different versions of GitLab
and Jenkins
you may want to use Docker
containers.
A example docker-compose file is available at gitlab-plugin/src/docker
which allows to set up instances of the latest GitLab
and Jenkins
versions.
To start the containers, run below command from the docker
folder:
docker-compose up -d
To access GitLab
, point your browser to http:https://172.17.0.1:10080
and set a password for the root
user account.
For more information on the supported GitLab
versions and how to configure the containers, visit Sameer Naik's github page at https://github.com/sameersbn/docker-gitlab.
To see Jenkins
, point your browser to http:https://localhost:8080
.
For more information on the supported Jenkins
tags and how to configure the containers, visit https://hub.docker.com/r/library/jenkins.
GitLab-Plugin admins should adhere to the following rules when releasing a new plugin version:
- Ensure codestyle conformity
- Run unit tests
- Run manual tests on both, oldest and latest GitLab versions
- Update documentation
- Create change log
- Create release tag
- Create release notes (on github)