End-to-End Multibranch Pipeline Project Creation

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

This tutorial shows you how to use Jenkins to orchestrate building and testing a simple Node.js and React application with the Node Package Manager (npm), as well as deliver different outcomes for development and production purposes.

Before starting this tutorial, it is recommended that you run through at least one of the initial set of Introductory tutorials from the Tutorials overview page first to familiarize yourself with CI/CD concepts (relevant to a technology stack you’re most familiar with), how these concepts are implemented in Jenkins and the fundamentals of Jenkins Pipelines.

In this tutorial, you’ll use the same application that the Build a Node.js and React app with npm tutorial is based on. Therefore, you’ll be building and testing the same application but this time, its delivery will be different depending on the Git branch that Jenkins builds from. That is, the branch being built determines which delivery stage of your Pipeline is executed.

Duration: This tutorial takes 30-50 minutes to complete (assuming you’ve already met the Prerequisites below). The exact duration will depend on the speed of your machine and whether you’ve already installed docker and docker compose.

You can stop this tutorial at any point in time and continue from where you left off.

Prerequisites

For this tutorial, you will require:

  • A macOS, Linux or Windows machine with:

    • 256 MB of RAM, although more than 2 GB 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.

Fork and clone the sample repository

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 command to create the development branch (from the contents of the master branch):

    git checkout development
  2. Push the development branch and set it to track the remote branch:

    git push -u origin development
  3. Run the following command to create the production branch (from the contents of the master branch):

    git checkout production
  4. Push the production branch and set it to track the remote branch:

    git push -u origin production
  5. Get back to the master branch:

    git checkout master
  6. Check that these branches now exist by running the command git branch, which should give you:

      development
    * master
      production

Start your Jenkins instance

  1. Obtain the latest Jenkins instance, customized for this tutorial, by cloning the quickstart-tutorials repository.

  2. After cloning, navigate to the quickstart-tutorials directory, and execute the command

    docker compose --profile multi up -d

    to run the example.

  3. Once the containers are running successfully (you can verify this with docker compose ps), the controller can be accessed at http://localhost:8080.

If you are unable to install docker compose on your machine for any reason, you can still run the example in the cloud for free thanks to GitPod. GitPod is free for 50 hours per month. You need to link it to your GitHub account so you can run the example in the cloud. Click on that link to open a new browser tab with a GitPod workspace where you’ll be able to start the Jenkins instance, and run the rest of the tutorial.

Now, log in using the admin username and admin password.

Create your Multibranch Pipeline project

  1. Go back to Jenkins and ensure you are logged in http://localhost:8080/ and have clicked New Item on the left.

  2. In the Enter an item name box, type building-a-multibranch-pipeline-project, select Multibranch Pipeline and click OK.

    Create a multibranch pipeline

  3. In the Display Name field, type Building a Multibranch Pipeline Project.

  4. In the Branch Sources section, click Add source and select GitHub.

  5. In the GitHub section, there is a field labeled Repository HTTPS URL. Enter https://github.com/YOUR-GITHUB-ACCOUNT-NAME/building-a-multibranch-pipeline-project.git, and click Validate.

    Credentials ok

  6. You can now click on Save to save your new Pipeline project.

  7. Jenkins will now scan your remote repository for branches and create a Pipeline for each branch that contains a Jenkinsfile.

    Found all branches

  8. Jenkins has found your three branches, and no pull requests for the time being.

  9. You can now scroll up and click on Building a Multibranch Pipeline Project to access the main page of your new Multibranch Pipeline project.

    Multibranch pipeline main page

  10. Jenkins found a Jenkinsfile in each branch, and it has already built each branch.

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 Jenkins detect that there’s something to build (i.e. the Jenkinsfile) immediately after creating the Multibranch Pipeline project, which in turn makes these branches accessible through the Jenkins interface.

If you created a Pipeline project, but created more branches later on, either:

  • Use the Scan Repository Now feature in the Multibranch Pipeline project 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 forked and locally cloned Git repository (building-a-multibranch-pipeline-project).

First, create an initial Pipeline to 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 any
        environment {
            CI = 'true'
        }
        stages {
            stage('Build') {
                steps {
                    sh 'npm install'
                }
            }
            stage('Test') {
                steps {
                    sh './jenkins/scripts/test.sh'
                }
            }
        }
    }

    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 npm tutorial.

  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 add Jenkinsfile
    then
    git commit -m "Add initial Jenkinsfile with 'Test' stage"
    and finally
    git push to push your changes to your forked repository on GitHub, so it can be picked up by Jenkins.

  4. Go back to Jenkins again, log in again if necessary, click on the Building a Multibranch Pipeline Project link if it is visible, or on Dashboard and then on the Building a Multibranch Pipeline Project link.

  5. You should see the list of branches detected on the previous steps. Look at the row containing master. There is a green triangle on the right side of this row (the run icon). Run icon Click on it.

    Schedule a build for master

  6. Click on master to see a new Pipeline being built.
    Master build after first modification

  7. Click on #2 or on the latest build number to see the details of the build.
    2nd build details

  8. Click on Pipeline Overview on the left to see the stages of the Pipeline.
    Pipeline overview

  9. Click on Test and then on the green part to see the details of the test stage.
    Test stage details

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 any
        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' (1)
                }
                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'  (1)
                }
                steps {
                    sh './jenkins/scripts/deploy-for-production.sh'
                    input message: 'Finished using the web site? (Click "Proceed" to continue)'
                    sh './jenkins/scripts/kill.sh'
                }
            }
        }
    }
    1 These when directives (along with their branch conditions) determine whether or not the stages (containing these when directives) 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 repository.

  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 add .
    then
    git commit -m "Add 'Deliver…​' and 'Deploy…​' stages"
    and finally
    git push to push your changes to your forked repository on GitHub, so it can be picked up by Jenkins.

  4. Go back to Jenkins again, log in again if necessary and go to the Dashboard.

  5. Click Building a Multibranch Pipeline Project to access the main page of your Multibranch Pipeline project.

  6. Click the run icon Run icon of the master branch of your Pipeline project.

  7. Click on master to see a new Pipeline being built.

  8. Click on #3 or on the latest build number to see the details of the build.

  9. Click on Pipeline Overview on the left to see the stages of the Pipeline.
    Complete Pipeline runs successfully on the 'master' branch

  10. 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.

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 and then

    • git push to push your changes to your forked repository on GitHub, so it can be picked up by Jenkins.

  2. Also run the following commands to pull changes from master to production:

    • git checkout production
      and

    • git pull . master and then

    • git push to push your changes to your forked repository on GitHub, so it can be picked up by Jenkins.

    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, navigate to the dashboard, and select Building a Multibranch Pipeline Project.

  2. Click the Run icon Run icon of the development branch of your Pipeline project on the far right to see Jenkins building the development branch with the amended Jenkinsfile.

  3. Select development to see a new Pipeline being built.
    Build development branch

  4. Select #2 (or the latest build number) on the left, and then Pipeline Overview on the left.
    Deliver for development

  5. Select the Deliver for development stage and then 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 might 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_modules directory 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.

  6. Ctrl-Click or Cmd-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.

  7. When you are finished viewing the page/site, go back to the Jenkins tab and select #2 (or the last number of your build), and then Paused for Input on the left hand side.
    Paused for input. Proceed

  8. Select the Proceed button to complete the Pipeline’s execution.

  9. Once more, select the #2 on top of the screen (or the last number of your build) and then Pipeline Overview on the left hand side to see the stages of the Pipeline.
    Complete Pipeline runs successfully on the 'development' branch

  10. Notice how the Deliver for development stage was executed but the Deploy for production stage was not.

Run your Pipeline on the production branch

  1. Go back to Jenkins again, log in again if necessary, navigate to the dashboard, and select Building a Multibranch Pipeline Project.

  2. Click the Run icon Run icon of the production branch of your Pipeline project on the far right to see Jenkins building the production branch with the amended Jenkinsfile.

  3. Select production to see a new Pipeline being built.
    Build production branch

  4. Select #2 (or the latest build number) on the left, and then Pipeline Overview on the left.
    iDeploy for production

  5. Select the Deploy for production stage and then 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

  6. Ctrl-Click or Cmd-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). Once 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.

  7. When you are finished viewing the page/site, go back to the Jenkins tab and select #2 (or the last number of your build), and then Paused for Input on the left hand side.
    Paused for input. Proceed

  8. Select the Proceed button to complete the Pipeline’s execution.

  9. Once more, select the #2 on top of the screen (or the last number of your build) and then Pipeline Overview on the left hand side to see the stages of the Pipeline.
    Complete Pipeline runs successfully on the 'production' branch

  10. The Deploy for production stage turns green if Jenkins built your Node.js and React application successfully from your production branch. Notice how the Deploy for production stage was executed but the Deliver for development stage was skipped. 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 simulated 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 production branch) 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 logo from './logo.svg';
    import './App.css';
    
    function App() {
      return (
        <div className="App">
          <header className="App-header">
            <img src={logo} className="App-logo" alt="logo" />
            <p>
              Edit <code>src/App.js</code> and save to reload.
            </p>
            <a
              className="App-link"
              href="https://reactjs.org"
              target="_blank"
              rel="noopener noreferrer"
            >
              Learn React<br/>
              This is a new line I added.
            </a>
          </header>
        </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 add src/App.js
    then
    git commit -m "Update 'App.js'" and finally
    git push to push your changes to your forked repository on GitHub, so it can be picked up by Jenkins.

  5. Back in Jenkins, 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-project directory, run the following set of commands to merge your change into the production branch (via the master branch):

    • git checkout master
      and

    • git pull . development
      and then

    • git push
      Once done with master, let’s move to production:

    • git checkout production
      and

    • git pull . master
      and then

    • git push

  7. Back in Jenkins, 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.

To learn more about what Jenkins can do, check out: