Getting started with Pipelines

Before you start

This tutorial assumes that you're new to Buildkite Pipelines. To begin, create a free, personal Buildkite account.

From the Start building for free page, do either of the following:

• Select Sign up with GitHub and then Authorize Buildkite to access your GitHub account.

  If prompted with the Install Buildkite page in GitHub, ensure All repositories is selected (recommended), although choose Only select repositories if you need to limit the scope of the installation.

  You should then be taken to the New Pipeline page, where you can begin creating your new pipeline.

• Select Continue with Email, then enter your Full name, Email address and Password, and select Sign up.

  1. Follow the instructions on the Verify your email page, and select the Buildkite verification link in the email message sent to this address.

  2. On the resulting Buildkite Create organization page, enter the name for your Buildkite organization.

     You should then be taken to the New Pipeline page, where you can begin creating your new pipeline.

Create a new pipeline

A pipeline is what represents a CI/CD workflow in Buildkite Pipelines. You define each pipeline with a series of steps to run. When you trigger a pipeline, you create a build, and steps are dispatched as jobs, which are run on agents. Jobs are independent of each other and can run on different agents.

If you signed up:

• With GitHub, the New Pipeline page's Git scope is set to your GitHub account, and its most recently updated repository is automatically selected in the Repository field.

  Note:

  • If you're new to Buildkite Pipelines and want to learn more about creating some pipelines, select Or try an example to examine the list of existing example pipelines you can build.
  • If your GitHub account is new and contains no repositories, the Starter pipeline of the Buildkite Examples is automatically selected.

• By email, the New Pipeline page presents the Starter pipeline of the Buildkite Examples.

Ensure you familiarize yourself with the New Pipeline page's functionality in Understanding the New Pipeline page before proceeding to build some example pipelines.

Understanding the New Pipeline page

The New Pipeline page has the following fields:

• Git scope: Allows you to select from the following list of options:

  • Your GitHub account or organization.
  • A selection of Buildkite Examples to start with, which allows you to learn more about how Buildkite Pipelines builds projects for a variety of different use cases.
  • The Use remote URL options allow you to select a GitLab, Bitbucket, or Any account, for any other remotely accessible Git repository. The Manage accounts option further down this list also allows you to configure connections to these repository providers.
  • The Connect GitHub account option allows you to do just that. This option is useful if you signed up by email, and need to connect your GitHub account to the Buildkite platform, and generates the same Install Buildkite step as part of the GitHub sign-up process.

• Repository: Select the Git repository available to your selected Git scope. Upon selecting a repository:

  • The Checkout using option appears, where you can select between SSH or HTTPS.
  • If you selected a repository which is not one of the Buildkite Examples, then the Build Triggers section may appear, which shows the actions that trigger a build of this pipeline. You can disable this triggering by clearing the Trigger builds when checkbox.

• Pipeline name: Buildkite Pipelines automatically generates a name for your pipeline, which is based on your repository's name. However, you can change this default name using this field.

• Description ( optional ): Enter a description for your pipeline, which will appear under the pipeline name on the main Pipelines page.

• Default Branch: The repository branch that your pipeline will build, unless instructed otherwise. Leave this unchanged for this tutorial.

• Teams: The Buildkite teams that have permission to build your pipeline.

  Note: If you just signed up to Pipelines, then this field won't be visible, as it's only shown once teams have been configured in your Buildkite account/organization. If this field is shown, leave it unchanged for this tutorial.

• Cluster: The Buildkite cluster whose configured agents will build your pipeline. Leave this unchanged for this tutorial.

• YAML Steps editor: This field allows you to define steps within your main Buildkite pipeline. To make things easier though, you can start with an initial pipeline from the Template dropdown. Using this dropdown, you can select from the following options:

  • Helper templates:
    • Hello world: For a simple example of how to structure commands in Buildkite pipeline YAML syntax.
    • Pipeline upload: To upload a Buildkite pipeline stored in your repository.
  • Example templates: This section lists pipelines which are used to build example projects available from the Repository field, when the Git scope has been set to Buildkite Examples.

Example pipelines

Ensure you're already familiar with the New Pipeline page's functionality (described in Understanding the New Pipeline page) before proceeding.

1. Ensure Buildkite Examples is selected in Git scope and select Starter pipeline.

2. In the YAML Steps editor, note the three steps that constitute this pipeline: build, test, and deploy, and the dependency order in which these steps' jobs will be run.

   Note: Without analyzing the pipeline syntax in too much detail, take note the annotation-related command that's part of the deploy step.

3. Select Create and run to create your first Starter pipeline. This button creates your Starter pipeline and runs its first build.

4. Once your build has completed, check its Annotations tab, which displays the content of the repository's .buildkite/annotation.md file.

Once you've seen how Buildkite Pipelines builds a simple pipeline like Starter pipeline, try creating and building other pipelines from the Buildkite Examples provided, which suit the technologies you've been working with.

More Buildkite example repositories are available from the Buildkite Resources Examples page.

Next steps

That's it! You've got yourself up and running with Buildkite Pipelines and have already created and built some new pipelines!

As part of this sign-up process, Pipelines set you up with a few default configurations behind the scenes. These include the following:

• A Buildkite cluster: Buildkite Pipelines requires that all of its pipelines are managed through a Buildkite cluster, which is a security feature that's used to organize queues. When a new Buildkite account/organization is created, a single cluster is created, called Default cluster. Learn more Buildkite clusters from the Clusters overview.
• A queue: When the Default cluster is created, a default queue, simply called queue is also created. When creating a personal Buildkite account, this queue is a Buildkite hosted queue, which runs Buildkite hosted agents. Learn more about queues from Queues overview and Buildkite hosted agents from its overview page.

While creating a new personal Buildkite account automatically sets you up to run Buildkite hosted agents, Buildkite also supports self-hosted agents, which you can manage in your own infrastructure. Learn more about the differences between these agent architectures in Buildkite Pipelines architecture.

Once you're familiar with building some Buildkite examples, next try creating your own pipeline.