Getting started

Before you start

To complete this tutorial, you'll need:

• A Buildkite account. If you don't have one already, create a free account.

  When you create a new organization as part of sign-up, you'll be guided through a flow to create and run a starter pipeline. Complete that before continuing, and keep your agent running to continue using it in this tutorial.

• To enable the YAML steps editor in Buildkite:

  • Open the YAML migration settings by selecting Settings > YAML Migration.
  • Select Use YAML Steps for New Pipelines, then confirm the action in the modal.

• Git. This tutorial uses GitHub, but Buildkite can work with any version control system.

Understand the architecture

Before creating a pipeline, take a moment to understand Buildkite's architecture and the advantages it provides. Buildkite uses a hybrid architecture to separate:

• The control panel
• The build environment

Buildkite runs the control panel as a SaaS product, and you run the build environment on your own infrastructure. In other words, Buildkite handles the orchestration, and you bring the compute. That means you can fine-tune and secure the build environment to suit your particular use case and workflow.

The hybrid architecture reduces the maintenance burden on your team compared to self-hosted solutions and gives you the security and control missing from fully SaaS build tools. See Hybrid architecture to learn more.

Install and run an agent

The program that executes work is called an agent in Buildkite. An agent is a small, reliable, and cross-platform build runner that connects your infrastructure to Buildkite. It polls Buildkite for work, runs jobs, and reports results. You can install agents on local machines, cloud servers, or other remote machines. You need at least one agent to run builds.

To install and run an agent:

1. Decide where you want to run the agent.

   Most engineers start by running an agent on their local machine while playing around with pipeline definitions before setting up a long-term solution.

2. Follow the instructions for where you want to install the agent.

   To install locally, see:

   • macOS
   • Windows
   • Linux
   • Docker

   Or see all installation options.

   Ensure you configure the agent token, which connects the agent to your Buildkite account.

To confirm that your agent is running, and configured correctly with your credentials, go to Agents. You should see a list of all agents linked to the account and their status.

Create a pipeline

Pipelines are how Buildkite represents a CI/CD workflow. 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 to run on agents. Jobs are independent of each other and can run on different agents.

Next, you'll create a new pipeline based on one of the following example pipelines:

• Bash example
• PowerShell example

Both result in the same behavior: the pipeline definition is uploaded from the repository (.buildkite/pipeline.yml), then a script runs that prints output to the logs.

To create a pipeline:

1. Select Add to Buildkite for the appropriate example based on where your agent is running.

   For Bash:

   

   For PowerShell:

   

2. Accept the pre-filled defaults by selecting Create Pipeline. This associates the example repository with your new pipeline.

3. Accept the pre-filled defaults by selecting Save and Build. This adds a step to upload the full pipeline definition from the repository.

4. In the modal that opens, create a build using the pre-filled details.

   1. Enter a message for the build. For example, My first build.
   2. Select Create Build.

The page for the build then opens and begins running:

Check the output

After triggering the build, you can view the output as it runs and the full results when complete. The output for each step shows in the job list.

Expand the row in the job list to view the output for a step. For example, selecting Example Script shows the following:

In the output, you'll see:

• A pre-command hook ran and printed some text in the logs.
• The agent checked out the repository.
• The agent can access different environment variables shown in the job environment.
• The script ran and printed text to the logs and uploaded an image as an artifact of the build.

Beyond the log, select one of the other tabs to see the artifacts, a timeline breakdown, and the environment variables.

Next steps

That's it! You've installed an agent, run a build, and checked the output. 🎉

We recommend you continue by creating your own pipeline.