Jenkins Cheatsheet

jenkins_cheatsheet.md

Jenkins Cheatsheet

N. P. O'Donnell, 2020-21

Run in Docker

Get the Jenkins docker image:

docker pull jenkins/jenkins

Run the image, listenting on localhost port 3000 - typical of reverse proxy setup.

docker run --restart unless-stopped -d -p 127.0.0.1:3000:8080 --name my-jenkins jenkins/jenkins

First Time Setup

Navigate to http://127.0.0.1:3000 (or domain if behind a proxy), you should see the Unlock Jenkins screen. On the docker host, grab the admin password:

docker exec my-jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Enter admin password, click continue. On the next screen click "Install suggested plugins", wait for plugins to get installed. Make a new user, set URL, start using Jenkins.

Installing Plugins

If you need to install a Jenkins plugin, click on the Jenkins icon on the top left, Manage Jenkins > Manage Plugins, click on the "Available" tab and search for the plugin(s) you want. Check them, and click "Install with restart". Jenkins will install the plugin(s) then restart.

Gitlab Integration

Note: Gitlab uses 2 kinds of "tokens" which can cause confusion:

1. API tokens, which consist of a single base64 string.
2. Deploy tokens which consist of a user/password combo.

The following steps will achieve a minimum setup where builds are triggered in the CI server when a new push is made to Gitlab.

Step 0: Create Project

Create a project called "my-project" in Gitlab with a basic Jenkinsfile:

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
	        sh 'echo hello'
                sh 'echo ${HOSTNAME}' 
            }
        }
    }
}

Commit and push these changes to Gitlab.

Step 1: Create Gitlab API Token

In Gitlab, go to Settings > Access Tokens and create a new token, and save it.

Step 2: Create Deploy Token

In Gitlab, navigate to the project in question, go to Settings > Repository > Deploy Tokens, Click expand. Create a new deploy token with at least read_repository scope and save it.

Step 3: Import API Token into Jenkins

In Jenkins, go to Manage Jenkins > Manage Credentials > Jenkins Store > (global). Click "Add Credentials". Choose the following settings:

• Kind = "Gitlab API token"
• Scope = "Global"
• API Token = <API token created in step 1>
• ID = "jenkins-api-token-1"
• Description = "Jenkins API Token 1"

Click OK.

Step 4: Import Deploy Token into Jenkins

In Jenkins, go to Manage Jenkins > Manage Credentials > Jenkins Store > (global). Click "Add Credentials". Choose the following settings:

• Kind = "Username with password"
• Scope = "Global"
• Username = <Username created in step 2>
• Password = <Password generated in step 2>
• ID = "jenkins-deploy-token-<projectname>"
• Description = "Jenkins deploy token for <projectname>"

Click OK.

Step 5: Configure Gitlab in Jenkins

In Jenkins, go to Manage Jenkins > Configure System, scroll down to "Gitlab" section. Ensure "Enable authentication for '/project' end-point" is checked, choose the following settings:

• Connection name = "Gitlab connection 1"
• Gitlab host URL = "https://gitlab.com"
• Credentials = <API token imported in step 3>

Click "Test connection", apply, save.

Step 6: Create Pipeline

In Jenkins, go to the homepage, click "New Item", enter the name "my-project", click "Pipeline", then click "OK".

Step 7: Set up Pipeline Definition

On the next screen (or by clicking on "my-project" from the Jenkins home screen, and clicking "Configure"), scroll down to Pipeline / Definition. From the drop-down menu, choose "Pipeline script from SCM", choose the following settings:

• SCM = "Git"
• Repository URL = <HTTPS repo URL> (Go to repo page on Gitlab, click Clone > Clone with HTTPS)
• Credentials = <Deploy token imported in step 4>
• Script path = "Jenkinsfile"

Click "Apply", click "Save".

Step 8: Perform a Manual Build in Jenkins

In Jenkins, click on "my-project" from the Jenkins home screen, then click "Build Now". A new entry will appear under "Build history and the build will begin. Click on the build then "Console Output" to see the build steps as they execute.

Step 9: Set up Gitlab User in Jenkins

In Jenkins, go to Manage Jenkins > Manage Users > Create User, choose the following settings:

• Username = <Choose a username>
• Password = <Choose a password>
• Full name = "Jenkins User"
• Email address = <Leave blank>

Make a note of the password, click "Create User".

Step 10: Set up Jenkins Integration in Gitlab

In Gitlab, go to "my-project" home page, navigate to Settings > Integrations > Jenkins CI, Enter the following settings:

• Enable integration = Checked
• Trigger > Push = Checked
• Jenkins url = <Base URL if your Jenkins instance> (must be reachable on the internet)
• Project name = "my-project"
• Username = <Username configured in step 9>
• Password = <Password configured in step 9>

Step 11: Set up Build Triggers

In Jenkins, click on "my-project" from the Jenkins home screen, then click "Configure". Under Build Triggers, ensure the following is checked:

• Build when a change is pushed to GitLab.
  • Push Events

Click "Apply", click "Save".

Step 12: Trigger Automatic Build by Pushing a Change

Go to the Jenkins home screen, then make a small change to the "my-project" codebase, commit it and push it to Gitlab. In a few seconds, Jenkins should receive a webhook notification from Gitlab and begin building with the new change.

Jobs

Job DSL

The job DSL allows Jenkins jobs to be defined programmatically. The Job DSL plugin must be installed before jobs can be executed programmatically.