Home Unlabelled End-to-End Multibranch Jenkins Pipeline Project Creation

End-to-End Multibranch Jenkins Pipeline Project Creation

February 12, 2019
Read
February 12, 2019


Prerequisites

For this tutorial, you will require:
  • A macOS, Linux or Windows machine with:
    • 256 MB of RAM, although more than 512MB is recommended.
    • 10 GB of drive space for Jenkins and your Docker images and containers.
  • The following software installed:
    • Docker - Read more about installing Docker in the Installing Docker section of the Installing Jenkins page.
      Note: If you use Linux, this tutorial assumes that you are not running Docker commands as the root user, but instead with a single user account that also has access to the other tools used throughout this tutorial.
    • Git and optionally GitHub Desktop.

Run Jenkins in Docker

In this tutorial, you’ll be running Jenkins as a Docker container from the jenkinsci/blueocean Docker image.
To run Jenkins in Docker, follow the relevant instructions below for either macOS and Linux or Windows.
You can read more about Docker container and image concepts in the Docker and Downloading and running Jenkins in Dockersections of the Installing Jenkins page.

On macOS and Linux

  1. Open up a terminal window.
  2. Run the jenkinsci/blueocean image as a container in Docker using the following docker run command (bearing in mind that this command automatically downloads the image if this hasn’t been done):
    docker run \
  --rm \
  -u root \
  -p 8080:8080 \
  -v jenkins-data:/var/jenkins_home \ 
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$HOME":/home \ 
  jenkinsci/blueocean
    Maps the /var/jenkins_home directory in the container to the Docker volume with the name jenkins-data. If this volume does not exist, then this docker run command will automatically create the volume for you.
    Maps the $HOME directory on the host (i.e. your local) machine (usually the /Users/<your-username> directory) to the /home directory in the container.
    Note: If copying and pasting the command snippet above doesn’t work, try copying and pasting this annotation-free version here:
    docker run \
  --rm \
  -u root \
  -p 8080:8080 \
  -v jenkins-data:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$HOME":/home \
  jenkinsci/blueocean
  3. Proceed to the Setup wizard.

On Windows

  1. Open up a command prompt window.
  2. Run the jenkinsci/blueocean image as a container in Docker using the following docker run command (bearing in mind that this command automatically downloads the image if this hasn’t been done):
    docker run ^
  --rm ^
  -u root ^
  -p 8080:8080 ^
  -v jenkins-data:/var/jenkins_home ^
  -v /var/run/docker.sock:/var/run/docker.sock ^
  -v "%HOMEPATH%":/home ^
  jenkinsci/blueocean
    For an explanation of these options, refer to the macOS and Linux instructions above.
  3. Proceed to the Setup wizard.

Accessing the Jenkins/Blue Ocean Docker container

If you have some experience with Docker and you wish or need to access the Jenkins/Blue Ocean Docker container through a terminal/command prompt using the docker exec command, you can add an option like --name jenkins-tutorials (with thedocker run above), which would give the Jenkins/Blue Ocean Docker container the name "jenkins-tutorials".
This means you could access the Jenkins/Blue Ocean container (through a separate terminal/command prompt window) with a docker exec command like:
docker exec -it jenkins-tutorials bash

Setup wizard

Before you can access Jenkins, there are a few quick "one-off" steps you’ll need to perform.
Unlocking Jenkins
When you first access a new Jenkins instance, you are asked to unlock it using an automatically-generated password.
  1. After the 2 sets of asterisks appear in the terminal/command prompt window, browse to http://localhost:8080 and wait until the Unlock Jenkins page appears.
    Unlock Jenkins page
  2. From your terminal/command prompt window again, copy the automatically-generated alphanumeric password (between the 2 sets of asterisks).
    Copying initial admin password
  3. On the Unlock Jenkins page, paste this password into the Administrator password field and click Continue.
Customizing Jenkins with plugins
After unlocking Jenkins, the Customize Jenkins page appears.
On this page, click Install suggested plugins.
The setup wizard shows the progression of Jenkins being configured and the suggested plugins being installed. This process may take a few minutes.
Creating the first administrator user
Finally, Jenkins asks you to create your first administrator user.
  1. When the Create First Admin User page appears, specify your details in the respective fields and click Save and Finish.
  2. When the Jenkins is ready page appears, click Start using Jenkins.
    Notes:
    • This page may indicate Jenkins is almost ready! instead and if so, click Restart.
    • If the page doesn’t automatically refresh after a minute, use your web browser to refresh the page manually.
  3. If required, log in to Jenkins with the credentials of the user you just created and you’re ready to start using Jenkins!

Stopping and restarting Jenkins

Throughout the remainder of this tutorial, you can stop the Jenkins/Blue Ocean Docker container by typing Ctrl-C in the terminal/command prompt window from which you ran the docker run …​ command above.
To restart the Jenkins/Blue Ocean Docker container:
  1. Run the same docker run …​ command you ran for macOS, Linux or Windows above.
    Note: This process also updates the jenkinsci/blueocean Docker image, if an updated one is available.
  2. Browse to http://localhost:8080.
  3. Wait until the log in page appears and log in.

Fork and clone the sample repository on GitHub

Obtain the simple "Welcome to React" Node.js and React application from GitHub, by forking the sample repository of the application’s source code into your own GitHub account and then cloning this fork locally.
  1. Ensure you are signed in to your GitHub account. If you don’t yet have a GitHub account, sign up for a free one on the GitHub website.
  2. Fork the building-a-multibranch-pipeline-project on GitHub into your local GitHub account. If you need help with this process, refer to the Fork A Repo documentation on the GitHub website for more information.
  3. Clone your forked building-a-multibranch-pipeline-project repository (on GitHub) locally to your machine. To begin this process, do either of the following (where <your-username> is the name of your user account on your operating system):
    • If you have the GitHub Desktop app installed on your machine:
      1. In GitHub, click the green Clone or download button on your forked repository, then Open in Desktop.
      2. In GitHub Desktop, before clicking Clone on the Clone a Repository dialog box, ensure Local Path for:
        • macOS is /Users/<your-username>/Documents/GitHub/building-a-multibranch-pipeline-project
        • Linux is /home/<your-username>/GitHub/building-a-multibranch-pipeline-project
        • Windows is C:\Users\<your-username>\Documents\GitHub\building-a-multibranch-pipeline-project
    • Otherwise:
      1. Open up a terminal/command line prompt and cd to the appropriate directory on:
        • macOS - /Users/<your-username>/Documents/GitHub/
        • Linux - /home/<your-username>/GitHub/
        • Windows - C:\Users\<your-username>\Documents\GitHub\ (although use a Git bash command line window as opposed to the usual Microsoft command prompt)
      2. Run the following command to continue/complete cloning your forked repo:
        git clone https://github.com/YOUR-GITHUB-ACCOUNT-NAME/building-a-multibranch-pipeline-project
        where YOUR-GITHUB-ACCOUNT-NAME is the name of your GitHub account.

Create development and production branches in your repository

Before creating your Pipeline project in Jenkins, create "development" and "production" branches of your locally cloned Git repository. You’ll be creating a single Jenkinsfile (initially in the master branch, which you’ll pull into the other branches) whose stages will be selectively executed based on the branch that Jenkins is building from.
Within the building-a-multibranch-pipeline-project directory (i.e. your local clone of the sample repository):
  1. Run the following commands to create these branches (from the contents of the master branch):
    • git branch development
      and
    • git branch production
  2. Check that these branches now exist by running the command git branch, which should give you:
      development
* master
  production
  3. If the asterisk (indicating the current branch) does not appear next to master, run the command git checkout master to ensure that master is the current branch.

Create your Pipeline project in Blue Ocean

Whenever you create any Pipeline project in Blue Ocean, Jenkins actually creates this as a multibranch Pipeline project behind the scenes. This becomes apparent if you were to access Jenkins’s classic interface after creating a Pipeline project in Blue Ocean; you’ll see that Jenkins will have created your project as a "Multibranch Pipeline" project.
  1. Go back to Jenkins and ensure you have accessed the Blue Ocean interface. To do this, make sure you:
    • have browsed to http://localhost:8080/blue and are logged in
      or
    • have browsed to http://localhost:8080/, are logged in and have clicked Open Blue Ocean on the left.
  2. In the Welcome to Jenkins box at the center of the Blue Ocean interface, click Create a new Pipeline to begin the Pipeline creation wizard.
    Note: If you don’t see this box, click New Pipeline at the top right.
  3. In Where do you store your code?, click Git (not GitHub).
  4. In the Repository URL field (within Connect to a Git repository), specify the directory path of your locally cloned repositoryabove, which is from your user account/home directory on your host machine, mapped to the /home directory of the Jenkins container - i.e.
    • For macOS - /home/Documents/GitHub/building-a-multibranch-pipeline-project
    • For Linux - /home/GitHub/building-a-multibranch-pipeline-project
    • For Windows - /home/Documents/GitHub/building-a-multibranch-pipeline-project
  5. Click Save to save your new Pipeline project.
    Blue Ocean detects the presence of the Jenkinsfile "Pipeline stub" in each branch and proceeds to run each Pipeline against its respective branch, whose build results are shown on the Activity page of the main Blue Ocean interface.
    Main Blue Ocean interface
The Pipeline stub consists of the basic requirements for a valid Pipeline - i.e. an agent and a stages section, as well as a stage directive.
The reason why the building-a-multibranch-pipeline-project repository includes a Jenkinsfile Pipeline stub is that its presence in a branch makes Blue Ocean detect that there’s something to build (i.e. the Jenkinsfile) immediately after creating the Pipeline project in Blue Ocean, which in turn makes these branches accessible through the Blue Ocean interface.
If you created a Pipeline project in Blue Ocean but didn’t have a Jenkinsfile in one or more of your repository’s branches, then to access the branches in Blue Ocean after subsequently pulling in/adding a Jenkinsfile to these branches, either:
  • Use the Scan Multibranch Pipeline Now feature in the Multibranch Pipeline project (accessible through Jenkins’s classic interface),
    or
  • Implement webhooks into your Git repository.

Create your initial Pipeline as a Jenkinsfile with build and test stages

You’re now ready to create the Pipeline that will automate building your Node.js and React application in Jenkins. Your Pipeline will be created as a Jenkinsfile, which will be committed to the master branch of your locally cloned Git repository (building-a-multibranch-pipeline-project).
First, create an initial Pipeline to download a Node Docker image and run it as a Docker container that will build your simple Node.js and React application. Also add a "Build" stage to the Pipeline to begin orchestrating this whole process and a "Test" stage to check that the application renders satisfactorily.
  1. Using your favorite text editor or IDE, open the existing Jenkinsfile at the root of your local building-a-multibranch-pipeline-project Git repository and clear its contents.
    Note: Be sure you are performing this step on the master branch of your repository.
  2. Copy the following Declarative Pipeline code and paste it into your empty Jenkinsfile:
    pipeline {
    agent {
        docker {
            image 'node:6-alpine'
            args '-p 3000:3000 -p 5000:5000' 
        }
    }
    environment {
        CI = 'true'
    }
    stages {
        stage('Build') {
            steps {
                sh 'npm install'
            }
        }
        stage('Test') {
            steps {
                sh './jenkins/scripts/test.sh'
            }
        }
    }
}
    This args parameter makes the Node container (temporarily) accessible through ports 3000 and 5000. The significance of this is explained in the jenkins/scripts/deliver-for-deployment.sh and jenkins/scripts/deploy-for-production.sh files of your cloned repository, and are covered in subsequent sections of this tutorial.
    Note: For an explanation of the other components of this Jenkinsfile, refer to the annotations of the Declarative Pipeline in the Create your initial Pipeline…​'' and Add a test stage…​'' sections of the Build a Node.js and React app with npmtutorial.
  3. Save your edited Jenkinsfile and commit it to your local building-a-multibranch-pipeline-project Git repository. E.g. Within the building-a-multibranch-pipeline-project directory, run the commands:
    git stage .
    then
    git commit -m "Add initial Jenkinsfile with 'Test' stage"
  4. Go back to Jenkins again, log in again if necessary and ensure you’ve accessed Jenkins’s Blue Ocean interface.
  5. Click Branches at the top right to access the list of your Pipeline project’s branches.
    Branches page
  6. Click the run icon Run icon of the master branch of your Pipeline project, then quickly click the OPEN link that appears briefly at the lower-right to see Jenkins building the master branch with the amended Jenkinsfile. If you weren’t able to click the OPENlink, click the top row on the Blue Ocean Activity page to access this feature.
    Within a few minutes, the Blue Ocean interface turns green if Jenkins built your Node.js and React application successfully from your master branch.
    Build and test stages run successfully with output
  7. Click the X at the top-right to return to the Activity page of the Blue Ocean interface.

Add deliver and deploy stages to your Pipeline

Next, add "Deliver for development" and "Deploy for production" stages to your Pipeline, which Jenkins will selectively execute based on the branch that Jenkins is building from.
This takes the "Pipeline-as-Code" concept to a new level, in which a single Jenkinsfile describes your project’s entire build, test, delivery and deployment processes in Jenkins for each branch of your repository. Read more about Pipeline and what a Jenkinsfile is in the Pipeline and Using a Jenkinsfile sections of the User Handbook.
  1. Go back to your text editor/IDE and ensure your Jenkinsfile is open.
  2. Copy and paste the following Declarative Pipeline syntax immediately under the Test stage of your Jenkinsfile:
            stage('Deliver for development') {
            when {
                branch 'development'
            }
            steps {
                sh './jenkins/scripts/deliver-for-development.sh'
                input message: 'Finished using the web site? (Click "Proceed" to continue)'
                sh './jenkins/scripts/kill.sh'
            }
        }
        stage('Deploy for production') {
            when {
                branch 'production'
            }
            steps {
                sh './jenkins/scripts/deploy-for-production.sh'
                input message: 'Finished using the web site? (Click "Proceed" to continue)'
                sh './jenkins/scripts/kill.sh'
            }
        }
    so that you end up with:
    pipeline {
    agent {
        docker {
            image 'node:6-alpine'
            args '-p 3000:3000 -p 5000:5000'
        }
    }
    environment {
        CI = 'true'
    }
    stages {
        stage('Build') {
            steps {
                sh 'npm install'
            }
        }
        stage('Test') {
            steps {
                sh './jenkins/scripts/test.sh'
            }
        }
        stage('Deliver for development') {
            when {
                branch 'development' 
            }
            steps {
                sh './jenkins/scripts/deliver-for-development.sh'
                input message: 'Finished using the web site? (Click "Proceed" to continue)'
                sh './jenkins/scripts/kill.sh'
            }
        }
        stage('Deploy for production') {
            when {
                branch 'production'  
            }
            steps {
                sh './jenkins/scripts/deploy-for-production.sh'
                input message: 'Finished using the web site? (Click "Proceed" to continue)'
                sh './jenkins/scripts/kill.sh'
            }
        }
    }
}
    These when directives (along with their branch conditions) determine whether or not the stages (containing these whendirectives) should be executed. If a branch condition’s value (i.e. pattern) matches the name of the branch that Jenkins is running the build from, then the stage that contains this when and branch construct will be executed.
    Notes:
    • For an explanation of the input message steps, refer to annotation 4 of the Declarative Pipeline at the ``Add a final deliver stage…​'' section of the Build a Node.js and React app tutorial.
    • For an explanation of the deliver-for-development.sh, deploy-for-production.sh and kill.sh script steps, refer to the contents of these files located in the jenkins/scripts directory from the root of the building-a-multibranch-pipeline-project respository.
  3. Save your edited Jenkinsfile and commit it to your local building-a-multibranch-pipeline-project Git repository. E.g. Within the building-a-multibranch-pipeline-project directory, run the commands:
    git stage .
    then
    git commit -m "Add 'Deliver…​' and 'Deploy…​' stages"
  4. Go back to Jenkins again, log in again if necessary and ensure you’ve accessed Jenkins’s Blue Ocean interface.
  5. Click Branches at the top right to access the list of your Pipeline project’s branches.
  6. Click the run icon Run icon of the master branch of your Pipeline project, then quickly click the OPEN link that appears briefly at the lower-right to see Jenkins building the master branch with the amended Jenkinsfile. If you weren’t able to click the OPENlink, click the top row on the Blue Ocean Activity page to access this feature.
    Notice how Jenkins skips the last two stages you added, since the branch you are running the build from (master) does not meet the when directives' branch conditions in these stages.
    Complete Pipeline runs successfully on the 'master' branch
  7. Click the X at the top-right to return to the Activity page of the Blue Ocean interface.

Pull your updated Jenkinsfile into the other repository branches

Now that you have a completed Jenkinsfile to build your application in Jenkins, you can pull this file from the master branch of your local repository into its development and production branches.
Within your local repository’s building-a-multibranch-pipeline-project directory:
  1. Run the following commands to pull changes from master to development:
    • git checkout development
      and
    • git pull . master
  2. Also run the following commands to pull changes from master to production:
    • git checkout production
      and
    • git pull . master
    Your development and production branches should now have all your Jenkinsfile updates you made on the master branch.

Run your Pipeline on the development branch

  1. Go back to Jenkins again, log in again if necessary and ensure you’ve accessed Jenkins’s Blue Ocean interface.
  2. Click Branches at the top right to access the list of your Pipeline project’s branches.
  3. Click the run icon Run icon of the development branch of your Pipeline project, then quickly click the OPEN link that appears briefly at the lower-right to see Jenkins building the development branch with the amended Jenkinsfile. If you weren’t able to click the OPEN link, click the top row on the Blue Ocean Activity page to access this feature.
  4. Within a few minutes and when the build pauses, ensure you are viewing the Deliver for development stage (click it if necessary), then click the top green Shell Script step to expand its contents and scroll down until you see the http://localhost:3000 link.
    Shell Script step 'Deliver for development' stage opened
    Note: Since you are building the application on a different branch, the npm install step will require a few minutes for npm to download the many dependencies required to run your Node.js and React application (stored in a local node_modulesdirectory within the Jenkins home directory). These dependencies are downloaded again because this Jenkins build would be the first time you are running your Pipeline project on the development branch and each branch has its own workspace directory (containing its own node_modules directory) within the Jenkins home directory.
  5. Click the http://localhost:3000 link to view your Node.js and React application running in development mode (with the npm start command) in a new web browser tab. You should see a page/site with the title Welcome to React on it.
  6. When you are finished viewing the page/site, click the Proceed button in Blue Ocean to complete the Pipeline’s execution.
    The Blue Ocean interface turns green if Jenkins built your Node.js and React application successfully from your developmentbranch. Notice how the Deliver for development stage was executed but the Deploy for production stage was not.
    Complete Pipeline runs successfully on the 'development' branch
  7. Click the X at the top-right to return to the Activity page of the Blue Ocean interface.

Run your Pipeline on the production branch

  1. Click Branches at the top right to access the list of your Pipeline project’s branches.
  2. Click the run icon Run icon of the production branch of your Pipeline project, then quickly click the OPEN link that appears briefly at the lower-right to see Jenkins building the production branch with the amended Jenkinsfile. If you weren’t able to click the OPEN link, click the top row on the Blue Ocean Activity page to access this feature.
  3. Within a few minutes and when the build pauses, ensure you are viewing the Deploy for production stage (click it if necessary), then click the top green Shell Script step to expand its contents and scroll down until you see the http://localhost:5000 link.
    Shell Script step 'Deploy for production' stage opened
  4. Click the http://localhost:5000 link to view your Node.js and React application in a new web browser tab. This will be running in production mode from a production build of your source code (generated using the npm run build command). Again, you should see a page/site with the title Welcome to React on it. However, this time, the application’s contents are served by the npm serve module and are also likely to continue running in the background in your browser.
  5. When you are finished viewing the page/site, click the Proceed button in Blue Ocean to complete the Pipeline’s execution.
    The Blue Ocean interface turns green if Jenkins built your Node.js and React application successfully from your productionbranch. Notice how the Deploy for production stage was executed but the Deliver for development stage was skipped.
    Complete Pipeline runs successfully on the 'production' branch
  6. Click the X at the top-right to return to the Activity page of the Blue Ocean interface.
    Note: Since your browser is likely to continue running the application’s content served by the npm serve module, your browser will still show the content you viewed at http://localhost:5000 long after Jenkins has killed off the serve process. Read more about how to clear the application and its content from your browser below.

Follow up (optional)

This section takes you through a similated development workflow using Jenkins, whereby changes made to your application (i.e. the App.js source file) can be examined from the development branch before they are deployed to production (from the productionbranch) via the master branch.
  1. Within your local repository’s building-a-multibranch-pipeline-project directory, run the command git checkout development to change to the development branch.
  2. Go back to your text editor/IDE and open the App.js file in the src directory of your local building-a-multibranch-pipeline-project Git repository.
  3. Copy and paste the following HTML syntax immediately under the To get started…​ line of your App.js file:
              <br/>
          This is a new line I added.
    so that you end up with:
    import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';

class App extends Component {
  render() {
    return (
      <div className="App">
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <h1 className="App-title">Welcome to React</h1>
        </header>
        <p className="App-intro">
          To get started, edit <code>src/App.js</code> and save to reload.
          <br/>
          This is a new line I added.
        </p>
      </div>
    );
  }
}

export default App;
  4. Save the edited App.js file and commit it to your local building-a-multibranch-pipeline-project Git repository. E.g. Within the building-a-multibranch-pipeline-project directory, run the commands:
    git stage .
    then
    git commit -m "Update 'App.js'"
  5. Back in Blue Ocean, run your Pipeline on the development branch (as you did above) and check the results through http://localhost:3000 to see your new line added.
  6. Assuming you’re happy with the change, then within your local repository’s building-a-multibranch-pipeline-projectdirectory, run the following set of commands to pull your change into the production branch (via the master branch):
    • git checkout master
      and
    • git pull . development
      then
    • git checkout production
      and
    • git pull . master
  7. Back in Blue Ocean, run your Pipeline on the production branch this time (as you did above) and check the results through http://localhost:5000 to see your new line added.
    Notes:
    • Since your browser is likely to cache the contents of the npm serve module, you may need to refresh your browser page to see your change.
    • In a real software development environment with small to large teams of people, pulling changes between branches is more likely to be conducted using pull requests on a cloud- or web-hosted Git service (such as GitHub or BitBucket).

Clearing the app from your browser

Your browser is likely to continue running your application’s content served by the npm serve module, which means that your browser will still show the content you viewed at http://localhost:5000 long after Jenkins has killed off the serve process. To clear the application and its content from your browser:

On Chrome

  1. Enter the following into your browser’s URL field:
    chrome://serviceworker-internals/
  2. Locate the "ServiceWorker" entry for http://localhost:5000
  3. Click its Unregister button.

On Firefox

  1. Enter the following into your browser’s URL field:
    about:serviceworkers
  2. Locate the "Registered Service Worker" entry for http://localhost:5000
  3. Click its Unregister button.

Wrapping up

Well done! You’ve just used Jenkins to build a multibranch Pipeline project with selectively run stages!
This tutorial demonstrated the power of using a single Jenkinsfile across multiple branches of your repository to orchestrate different build and delivery outcomes in Jenkins.
Because Jenkins is extremely extensible, it can be modified and configured to handle practically any aspect of build orchestration and automation.
Tags :

No comments:

Subscribe to: Post Comments ( Atom )
Powered by Blogger.