Creating a Pipeline

Table of Contents

Setting up your Pipeline project

Blue Ocean makes it easy to create a Pipeline project in Jenkins.

A Pipeline can be generated from an existing Jenkinsfile in source control, or you can use the Blue Ocean Pipeline editor to create a new Pipeline for you (as a Jenkinsfile that will be committed to source control).

Setting up your Pipeline project

To start setting up your Pipeline project in Blue Ocean, at the top-right of the Blue Ocean Dashboard, click the New Pipeline button.

If your Jenkins instance is new or has no Pipeline projects or other items configured (and the Dashboard is empty), Blue Ocean displays a Welcome to Jenkins message box on which you can click the Create a new Pipeline button to start setting up your Pipeline project.

Welcome to Jenkins - Create a New Pipeline message box

You now have a choice of creating your new Pipeline project from a:

standard Git repository
repository on GitHub or GitHub Enterprise
repository on Bitbucket Cloud or Bitbucket Server

For a Git repository

To create your Pipeline project for a Git repository, click the Git button under Where do you store your code?

Where do you store your code

In the Connect to a Git repository section, enter the URL for your Git repository in the Repository URL field.

Connect to a Git repository

You now need to specify a local or a remote repository from which to build your Pipeline project.

Local repository

If your URL is a local directory path (e.g., beginning with a forward slash / such as /home/cloned-git-repos/my-git-repo.git), you can proceed to click the Create Pipeline button.

Blue Ocean will then scan your local repository’s branches for a Jenkinsfile and will commence a Pipeline run for each branch containing a Jenkinsfile. If Blue Ocean cannot find any Jenkinsfile, you will be prompted to begin creating one through the Pipeline editor.

Local repositories are typically limited to file system access. They are usually only visible from the controller node. Local repositories are also known to require more complicated path names on Windows computers than most users want to manage. Users are advised to run jobs on agents rather than running them directly on the controller. For those reasons, use a remote repository rather than a local repository for the best Blue Ocean experience.

Remote repository

Since the Pipeline editor saves edited Pipelines to Git repositories as Jenkinsfiles, Blue Ocean only supports connections to remote Git repositories over the SSH protocol.

If your URL is for a remote Git repository, then as soon as you begin typing the URL, starting with either:

ssh:// - e.g. ssh://gituser@git-server-url/git-server-repos-group/my-git-repo.git
or
user@host:path/to/git/repo.git - e.g. gituser@git-server-url:git-server-repos-group/my-git-repo.git,

Blue Ocean automatically generates an SSH public/private key pair (or presents you with an existing one) for your current/logged in Jenkins user. This credential is automatically registered in Jenkins with the following details for this Jenkins user:

Domain: blueocean-private-key-domain
ID: jenkins-generated-ssh-key
Name: <jenkins-username> (jenkins-generated-ssh-key)

You need to ensure that this SSH public/private key pair has been registered with your Git server before continuing. If you have not already done this, follow these two steps. Otherwise, continue on.

Configure the SSH public key component of this key pair (which you can copy and paste from the Blue Ocean interface) for the remote Git server’s user account (e.g., within the authorized_keys file of the machine’s gituser/.ssh directory).
Note: This process allows your Jenkins user to access the repositories that your Git server’s user account (e.g. gituser) has access to. Read more about this in Setting Up the Server of the Pro Git documentation.
When done, return to the Blue Ocean interface.

Click the Create Pipeline button.

Blue Ocean will then scan your local repository’s branches for a Jenkinsfile and will commence a Pipeline run for each branch containing a Jenkinsfile. If Blue Ocean cannot find any Jenkinsfile you will be prompted to begin creating one through the Pipeline editor.

For a repository on GitHub

To create your Pipeline project directly for a repository on GitHub, click the GitHub button under Where do you store your code?

Where do you store your code

In the Connect to GitHub section, enter your GitHub access token into the Your GitHub access token field.
If you previously configured Blue Ocean to connect to GitHub using a personal access token, Blue Ocean takes you directly to the choosing your GitHub account/organization and repository steps below:

Connect to GitHub

If you do not have a GitHub access token, click the Create an access key here link to open GitHub to the New personal access token page.

Create your access token

In the new tab, sign in to your GitHub account (if necessary), and on the GitHub New Personal Access Token page, specify a brief Token description for your GitHub access token (e.g. Blue Ocean).
Note: An access token is usually an alphanumeric string that represents your GitHub account along with permissions to access various GitHub features and areas through your GitHub account. The new access token process (triggered through the Create an access key here link above) has the appropriate permissions pre-selected, which Blue Ocean requires to access and interact with your GitHub account.
Scroll down to the end of the page and click Generate token.
On the resulting Personal access tokens page, copy your newly generated access token.
Back in Blue Ocean, paste the access token into the Your GitHub access token field and click Connect.
Your current/logged in Jenkins user now has access to your GitHub account (provided by your access token), so you can now choose your GitHub account/organization and repository.
Jenkins registers this credential with the following details for this Jenkins user:
- Domain: blueocean-github-domain
- ID: github
- Name: <jenkins-username>/****** (GitHub Access Token)

Choose your GitHub account/organization and repository

At this point, Blue Ocean prompts you to choose your GitHub account or an organization you are a member of, as well as the repository it contains from which to build your Pipeline project.

In the Which organization does the repository belong to? section, click either:
- Your GitHub account to create a Pipeline project for one of your own GitHub repositories or one which you have forked from elsewhere on GitHub.
- The organization of which you are a member, to create a Pipeline project for a GitHub repository located within this organization.
In the Choose a repository section, click the repository (within your GitHub account or organization) from which to build your Pipeline project.
Tip: If your list of repositories is long, you can filter this list using the Search option.
Click Create Pipeline.
Blue Ocean will then scan your local repository’s branches for a Jenkinsfile and will commence a Pipeline run for each branch containing a Jenkinsfile. If Blue Ocean cannot find any Jenkinsfile, you will be prompted to begin creating one through the Pipeline editor (by clicking Create Pipeline again).
Note: Under the hood, a Pipeline project created through Blue Ocean is actually a "multibranch Pipeline." Therefore, Jenkins looks for the presence of at least one Jenkinsfile in any branch of your repository.

For a repository on Bitbucket Cloud

To create your Pipeline project directly for a Git or Mercurial repository on Bitbucket Cloud, click the Bitbucket Cloud button under Where do you store your code?

Where do you store your code

In the Connect to Bitbucket section, enter your Bitbucket email address and password into the Username and Password fields, respectively. Note that:

If you previously configured Blue Ocean to connect to Bitbucket with your email address and password, Blue Ocean takes you directly to the choosing your Bitbucket account/team and repository steps below.
If you entered these credentials, Jenkins registers them with the following details for this Jenkins user:
- Domain: blueocean-bitbucket-cloud-domain
- ID: bitbucket-cloud
- Name: <bitbucket-user@email.address>/****** (Bitbucket server credentials)

Connect to Bitbucket

Click Connect, and your current/logged in Jenkins user will now have access to your Bitbucket account. You can now choose your Bitbucket account/team and repository.

Choose your Bitbucket account/team and repository

At this point, Blue Ocean prompts you to choose your Bitbucket account or a team you are a member of, as well as the repository it contains from which to build your Pipeline project.

In the Which team does the repository belong to? section, click either:
- Your Bitbucket account to create a Pipeline project for one of your own Bitbucket repositories or one which you have forked from elsewhere on Bitbucket.
- A team of which you are a member to create a Pipeline project for a Bitbucket repository located within this team.
In the Choose a repository section, click the repository (within your Bitbucket account or team) from which to build your Pipeline project.
Tip: If your list of repositories is long, you can filter this list using the Search option.
Click Create Pipeline.
Blue Ocean will then scan your local repository’s branches for a Jenkinsfile and will commence a Pipeline run for each branch containing a Jenkinsfile. If Blue Ocean cannot find any Jenkinsfile, you will be prompted to begin creating one through the Pipeline editor (by clicking Create Pipeline again).
Note: Under the hood, a Pipeline project created through Blue Ocean is actually a "multibranch Pipeline." Therefore, Jenkins looks for the presence of at least one Jenkinsfile in any branch of your repository.