Jenkins User Documentation Home

Guided Tour

Tutorials

User Handbook (PDF)

Resources

Recent Tutorial Blog Posts
View all tutorial blog posts

⇑ Blue Ocean
Index

Create a Pipeline

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

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

<em>New Pipeline Button</em>

On a new Jenkins instance or if Jenkins has no existing jobs or Pipelines and the Dashboard is empty, Blue Ocean will also display a message box on which you can click the Create a New Pipeline button to start setting up your Pipeline project.

<em>Welcome to Jenkins - Create a New Pipeline message box</em>

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

For a Git repository

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

<em>Where do you store your code</em>

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

<em>Connect to a Git repository</em>

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-repositories/my-git-repository.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 Blue Ocean Pipeline editor.

Remote repository

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@server-url/git-server-repositories/my-git-repository.git
    or

  • user@host:path/to/git/repo.git - e.g. gituser@server-url:git-server-repositories/my-git-repository.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 2 steps. Otherwise, continue on.

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

  2. 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 Blue Ocean Pipeline editor.

Since the Blue Ocean Pipeline editor saves edited Pipelines to Git repositories as Jenkinsfile‍s, Blue Ocean does not support other Git connection protocols like HTTP or HTTPS. Therefore, you will need to configure Blue Ocean’s public SSH key with your Git server instead (as described above), or by using one of the other hosted Git server options documented on this page.

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?

<em>Where do you store your code</em>

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.

<em>Connect to GitHub</em>

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

  1. 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 respresents 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.

  2. Scroll down to the end of the page and click Generate token.

  3. On the resulting Personal access tokens page, copy your newly generated access token.

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

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

    • An organization you are a member of to create a Pipeline project for a GitHub repository located within this organization.

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

    <em>Choose a repository</em>

  3. 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 Blue Ocean Pipeline editor (by clicking Create Pipeline again).
    Note: Under the hood, a Pipeline project created through Blue Ocean is actually "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?

<em>Where do you store your code</em>

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)

<em>Connect to Bitbucket</em>

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.

  1. 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 you are a member of to create a Pipeline project for a Bitbucket repository located within this team.

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

    <em>Choose a repository</em>

  3. 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 Blue Ocean Pipeline editor (by clicking Create Pipeline again).
    Note: Under the hood, a Pipeline project created through Blue Ocean is actually "multibranch Pipeline". Therefore, Jenkins looks for the presence of at least one Jenkinsfile in any branch of your repository.

⇑ Blue Ocean
Index

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.