Deprecation Notice: This tutorial is out-of-date and is only preserved for educational purposes. These steps no longer work on the GitLab Demo Systems.
GitLab’s Jenkins integration allows you to trigger a Jenkins build when you push code to a repository, or when a merge request is created. Additionally, it shows the pipeline status on merge requests widgets and on the project’s home page.
This tutorial shows you how to create a project with a Jenkinsfile
, configure a project on the Jenkins server, configure the GitLab Jenkins integration plugin, enable the integration on your GitLab project, and perform a commit to show how pipelines are integrated between GitLab and Jenkins.
If you are just getting started with Jenkins, please follow the instructions in Option A to use our tutorial app that is a Ruby application with a pre-created Jenkinsfile
.
If you're using your own existing project, please follow the instructions in Option B to add a Jenkinsfile
to your application.
Tutorial App - Jenkins Pipeline
and click the Use template button.Tutorial App - Jenkins Pipeline
Groups > demosys-users/{MY-USERNAME}
tutorial-app-jenkins-pipeline
(leave blank)
Private
Jenkinsfile
to your existing projectNote: a Jenkinsfile
will only be used if you create a pipeline job. You can skip this step if you want to show the integration with a freestyle job defined in Jenkins instead. Configuration for both options is included in this tutorial.
If you're using your own project, you will need to create a new file named Jenkinsfile
(without a file extension) in the root level of your project where your README file is.
/app/
...
.gitignore
Jenkinsfile
README.md
As a starting point, you can use an example that shows a few basic Jenkins stages that will report status back to GitLab. Note: this Jenkinsfile does not actually perform a build or test, it just shows where the specific commands for build and test should go, using an echo
.
pipeline {
agent any
stages {
stage('build') {
steps {
echo 'Notify GitLab'
updateGitlabCommitStatus name: 'build', state: 'pending'
echo 'build step goes here'
updateGitlabCommitStatus name: 'build', state: 'success'
}
}
stage(test) {
steps {
echo 'Notify GitLab'
updateGitlabCommitStatus name: 'test', state: 'pending'
echo 'test step goes here'
updateGitlabCommitStatus name: 'test', state: 'success'
}
}
}
}
There are additional examples provided in the Jenkins docs based on the language of your application.
You can reference the Jenkins docs for more detailed pipeline configurations, however that is outside the scope of this tutorial.
You can reference the open source Jenkins GitLab plugin documentation for more information on additional options.
In the Demo Cloud, we have configured the Jenkins server to use GitLab OAUTH for authentication. Keep in mind that this uses your Demo Cloud credentials and not your GitLab.com credentials.
Keep in mind that this is a shared environment and it is best practice create a folder with your username to keep your pipelines in and keep things tidy on the dashboard.
jeffersonmartin
).If you don't remember your username, switch back to the tab with the GitLab project. If you look in the browser URL, you can determine your username based on the path to your project.
It is understandable that the Jenkins UI can be a challenge to navigate. If you have any challenges, simply click on the Jenkins logo in the top left to go back to the dashboard and navigate from there.
Example
tutorial-app-jenkins-pipeline
One of the cosmetic limitations of the integration is that the GitLab integration use the integration built for GitHub so there is some nomenclature overlap that use the same underlying Git integration.
Example
https://gitlab-core.us.gitlabdemo.cloud/demosys-users/jeffersonmartin/tutorial-app-jenkins-pipeline
GitLab Core US
option from the dropdown menu if it's not already selected. This connection was configured by the system administrator earlier.
Example
https://gitlab-core.us.gitlabdemo.cloud/demosys-users/jeffersonmartin/tutorial-app-jenkins-pipeline
You may get an error message about connection error. This is expected behavior since there are no credentials selected. Simply proceed to the next step to select credentials from the dropdown menu.
integ_jenkins
option. Do not add new credentials in the demo environment.After you select the
integ_jenkins
option, the Jenkins server attempts to connect to the API of the GitLab instance to locate your repository URL. If successful, the error message will disappear automatically.
origin
.+refs/heads/*:refs/remotes/origin/* +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
*/master
field so that it is blank. This allows jobs to run for all branches (useful when testing a MR).
Build when a change is pushed to GitLab
. Leave all options at their default value.
Set build status to "pending" on GitHub commit
option.Publish build status to GitLab
option.One of the cosmetic limitations of the integration is that the GitLab integration use the integration built for GitHub so there is some nomenclature overlap that use the same underlying Git integration.
Example
https://gitlab-core.us.gitlabdemo.cloud/demosys-users/jeffersonmartin/tutorial-app-jenkins-pipeline
GitLab Core US
option from the dropdown menu if it's not already selected. This connection was configured by the system administrator earlier.
Build when a change is pushed to GitLab
. Leave all options at their default value.
Pipeline Script from SCM
Git
Example
https://gitlab-core.us.gitlabdemo.cloud/demosys-users/jeffersonmartin/tutorial-app-jenkins-pipeline
You may get an error message about connection error. This is expected behavior since there are no credentials selected. Simply proceed to the next step to select credentials from the dropdown menu.
integ_jenkins
option. Do not add new credentials in the demo environment.After you select the
integ_jenkins
option, the Jenkins server attempts to connect to the API of the GitLab instance to locate your repository URL. If successful, the error message will disappear automatically.
*/master
field with origin/$gitlabSourceBranch
Jenkinsfile
as is.Lightweight checkout
checkedIn the demo environment, each user generates their own API Token. In a production environment, you may want to create a service account-style user for the integration to simplify administration of API tokens if your security practices allow for that.
Default name
placeholder, type in GitLab integration
an click Generate.If you navigate away from this page without copying the token, you will need to generate a new key since this token will not be visible again.
We will configure the integration in GitLab. In some of the plugin documentation, you will see configuration instructions for webhooks which are the previous generation of the integration. Although webhooks can be used, they do not provide the depth of integration that GitLab offers now.
If you still have your GitLab project in a different browser tab or window, you can skip to step 5.
Tutorial App - Jenkins Pipeline
).Jenkinsfile
exists in the root of the repository. You do not need to make any changes.If the file does not exist, go back to Task 1 to create a
Jenkinsfile
or ensure that you're looking at the same GitLab project you started with earlier.
Default to Auto DevOps pipeline
. Click Save changes.
https://jenkins.us.gitlabdemo.cloud
{foldername}/{projectname}
notation.Example
jeffersonmartin/tutorial-app-jenkins-pipeline
If you get an error message, you may need to debug and see if your variables are correct. This is a common area to experience a problem and some light troubleshooting usually fixes the issue.
README.md
file and click on the filename.Pipelines must succeed
to ensure that code is built and tested successfully prior to being merged to master.Jenkins
job. If you integrated a pipeline job using the suggested Jenkinsfile, you should see two jobs - build
and test
. Right click on any job and select Open Link in New Tab.
You have successfully integrated your GitLab project with Jenkins CI.
There are several approaches to the authentication (shared vs per-user vs per-project), so please consider the best option for your environment when integrating Jenkins.
To learn more about the Jenkins integration, please see the official GitLab documentation.
You can also learn more in the jenkinsci/gitlab-plugin
open source integration's README documentation on GitHub.
To learn more about using Jenkins with stages and multiple steps beyond our basic example, please see the Jenkins documentation.