README
¶
Buildkite Agent
The buildkite-agent is a small, reliable, and cross-platform build runner that makes it easy to run automated builds on your own infrastructure. It’s main responsibilities are polling buildkite.com for work, running build jobs, reporting back the status code and output log of the job, and uploading the job's artifacts.
Full documentation is available at buildkite.com/docs/agent.
$ buildkite-agent --help
Usage:
buildkite-agent <command> [options...]
Available commands are:
acknowledgements Prints the licenses and notices of open source software incorporated into this software.
start Starts a Buildkite agent
annotate Annotate the build page within the Buildkite UI with text from within a Buildkite job
annotation Make changes to an annotation on the currently running build
artifact Upload/download artifacts from Buildkite jobs
env Process environment subcommands
lock Process lock subcommands
meta-data Get/set data from Buildkite jobs
oidc Interact with Buildkite OpenID Connect (OIDC)
pipeline Make changes to the pipeline of the currently running build
step Get or update an attribute of a build step
bootstrap Run a Buildkite job locally
help Shows a list of commands or help for one command
Use "buildkite-agent <command> --help" for more information about a command.
Dependencies
The agent is fairly portable and should run out of the box on most supported
platforms without extras. On Linux hosts it requires dbus.
Installing
The agents page on Buildkite has personalised instructions, or you can refer to the Buildkite docs. Both cover installing the agent with Ubuntu (via apt), Debian (via apt), macOS (via homebrew), Windows and Linux.
Docker
We also support and publish Docker Images for the following operating systems. Docker images are tagged using the agent SemVer components followed by the operating system.
For example, agent version 3.45.6 is published as:
- 3-ubuntu-20.04, tracks minor and bugfix updates in version 3 installed in Ubuntu 20.04
- 3.45-ubuntu-20.04, tracks bugfix updates in version 3.45 installed in Ubuntu 20.04
- 3.45.6-ubuntu-20.04, tracks the exact version installed in Ubuntu 20.04
Supported operating systems
- Alpine 3.18
- Ubuntu 18.04 LTS (x86_64), supported to end of standard support for 18.04
- Ubuntu 20.04 LTS (x86_64), supported to end of standard support for 20.04
- Ubuntu 22.04 LTS (x86_64), supported to end of standard support for 22.04
Starting
To start an agent all you need is your agent token, which you can find on your Agents page within Buildkite, and a build path. For example:
buildkite-agent start --token=<your token> --build-path=/tmp/buildkite-builds
Telemetry
By default, the agent sends some information back to the Buildkite mothership on
what features are in use on that agent. Nothing sensitive or identifying is sent
back to Buildkite, but if you want, you can disable this feature reporting by
adding the --no-feature-reporting flag to your buildkite-agent start call.
Features that we track can be found inside
AgentStartConfig.Features.
Development
These instructions assume you are running a recent macOS, but could easily be adapted to Linux and Windows.
# Make sure you have Go installed.
brew install go
# Download the code somewhere - no GOPATH required.
git clone https://github.com/buildkite/agent.git
cd agent
# Create a temporary builds directory.
mkdir /tmp/buildkite-builds
# Build an agent binary and start the agent.
go build -o /usr/local/bin/buildkite-agent .
buildkite-agent start --debug --build-path=/tmp/buildkite-builds --token "abc"
# Or, run the agent directly and skip the build step.
go run *.go start --debug --build-path=/tmp/buildkite-builds --token "abc"
Go Version and Dependency Management
The latest agent version is typically compiled with the highest-numbered stable release of Go. Previous Go versions may work, but are not guaranteed to. We are using newer language features such as generics, so compiling on Go < 1.18 will fail.
We're using Go Modules to manage our Go dependencies. Dependencies are not vendored into the repository unless necessary.
The Go module published by this repo (i.e. the one you could use by adding import "github.com/buildkite/agent/v3" to your code)
is not considered to be versioned using semantic versioning. Breaking changes may be introduced in minor releases. Use
the agent as a runtime depedency of your Go app at your own risk.
Platform Support
We provide support for security and bug fixes on the current major release only.
Our architecture and operating system support is primarily limited by what Go itself supports.
Architecture Support
We offer support for the following machine architectures (inspired by the Rust language platform support guidance).
Tier 1, guaranteed to work
- linux x86_64
- linux arm64
- windows x86_64
Tier 2, guaranteed to build
- linux x86
- windows x86
- darwin x86_64
- darwin arm64
Tier 3, community supported
We release binaries for various other platforms, and it should be possible to build the agent anywhere supported by Go, but official support is not provided for these Tier 3 platforms.
Operating System Support
We currently provide support for running the Buildkite Agent on the following operating systems. Future minor releases may drop support for end-of-life operating systems (typically as they become unsupported by the latest stable Go release).
The agent binary is fairly portable and should run out of the box on most UNIX like systems, as well as Windows.
- Ubuntu 18.04 and newer
- Debian 8 and newer
- Red Hat RHEL 7 and newer
- CentOS
- CentOS 7
- CentOS 8
- Amazon Linux 2
- macOS [^1]
- 10.15 (Catalina)
- 11 (Big Sur)
- 12 (Monterey)
- 13 (Ventura)
- 14 (Sonoma)
- Windows Server
- 2016
- 2019
- 2022
[^1]: See https://github.com/golang/go/issues/23011 for macOS / Go support and Supported macOS Versions for the last supported version of the Buildkite Agent for versions of macOS prior to those listed above.
Contributing
Contributors
Many thanks to our fine contributors! You're all amazing, and we greatly appreciate your input ❤️
Copyright
Copyright (c) 2014-2023 Buildkite Pty Ltd. See LICENSE for details.
Documentation
¶
Overview ¶
Buildkite-agent is a small, reliable, cross-platform build runner that makes it easy to run automated builds on your own infrastructure.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agent provides the key agent components - workers, worker pool, job runner, log streamer, artifact up/downloaders, etc.
|
Package agent provides the key agent components - workers, worker pool, job runner, log streamer, artifact up/downloaders, etc. |
|
plugin
Package plugin provides types for managing agent plugins.
|
Package plugin provides types for managing agent plugins. |
|
Package api provides an API client for the Buildkite Pipelines API.
|
Package api provides an API client for the Buildkite Pipelines API. |
|
Package clicommand contains the definitions of buildkite-agent subcommands.
|
Package clicommand contains the definitions of buildkite-agent subcommands. |
|
Package cliconfig provides a configuration file loader.
|
Package cliconfig provides a configuration file loader. |
|
Package core implements core functions wrapped up in a tasty library package.
|
Package core implements core functions wrapped up in a tasty library package. |
|
Package env provides utilities for dealing with environment variables.
|
Package env provides utilities for dealing with environment variables. |
|
internal
|
|
|
agentapi
Package agentapi provides an API for interacting with the agent.
|
Package agentapi provides an API for interacting with the agent. |
|
agenthttp
Package agenthttp creates standard Go [net/http.Client]s with common config options.
|
Package agenthttp creates standard Go [net/http.Client]s with common config options. |
|
bkgql
package bkgql contains a client to the Buildkite GraphQL API
|
package bkgql contains a client to the Buildkite GraphQL API |
|
experiments
Package experiments provides a global registry of enabled and disabled experiments.
|
Package experiments provides a global registry of enabled and disabled experiments. |
|
job
package job provides management of the phases of execution of a Buildkite job.
|
package job provides management of the phases of execution of a Buildkite job. |
|
job/hook
Package hook provides management and execution of hook scripts, and the ability to capture environment variable changes caused by scripts.
|
Package hook provides management and execution of hook scripts, and the ability to capture environment variable changes caused by scripts. |
|
job/integration
Package integration defines a series of integration tests for the job executor.
|
Package integration defines a series of integration tests for the job executor. |
|
job/shell
Package shell provides a cross-platform virtual shell abstraction for executing commands.
|
Package shell provides a cross-platform virtual shell abstraction for executing commands. |
|
mime
Package mime provides an extended mapping of file extensions to MIME types.
|
Package mime provides an extended mapping of file extensions to MIME types. |
|
osutil
Package osutil provides some OS-level helper functions.
|
Package osutil provides some OS-level helper functions. |
|
redact
Package redact provides functions for determining values to redact.
|
Package redact provides functions for determining values to redact. |
|
replacer
Package replacer provides an efficient configurable string replacer.
|
Package replacer provides an efficient configurable string replacer. |
|
shellscript
Package shellscript contains helpers for dealing with shell scripts.
|
Package shellscript contains helpers for dealing with shell scripts. |
|
socket
Package socket provides common implementations for local APIs that use HTTP over Unix domain sockets.
|
Package socket provides common implementations for local APIs that use HTTP over Unix domain sockets. |
|
stdin
Package stdin provides a cross-platform method for determining if standard input is readable.
|
Package stdin provides a cross-platform method for determining if standard input is readable. |
|
system
Package system provides a way to log OS-specific platform information.
|
Package system provides a way to log OS-specific platform information. |
|
tempfile
package tempfile provides a way to create temporary files preserving extension and setting permissions
|
package tempfile provides a way to create temporary files preserving extension and setting permissions |
|
jobapi provides an API with which to interact with and mutate the currently executing job Pronunciation: /ˈdʒɑbapi/ /joh-bah-pee/
|
jobapi provides an API with which to interact with and mutate the currently executing job Pronunciation: /ˈdʒɑbapi/ /joh-bah-pee/ |
|
Package lock provides a client for the Agent API locking service.
|
Package lock provides a client for the Agent API locking service. |
|
Package logger provides a logger abstraction for writing log messages in configurable formats to different outputs, such as a console, plain text file, or a JSON file.
|
Package logger provides a logger abstraction for writing log messages in configurable formats to different outputs, such as a console, plain text file, or a JSON file. |
|
Package metrics provides a wrapper around Datadog metrics collection.
|
Package metrics provides a wrapper around Datadog metrics collection. |
|
Package pool provides a worker pool that enforces an upper limit on concurrent workers.
|
Package pool provides a worker pool that enforces an upper limit on concurrent workers. |
|
Package process provides a helper for running and managing a subprocess.
|
Package process provides a helper for running and managing a subprocess. |
|
Package status provides a status page handler, for exposing a summary of what the various pieces of the agent are doing.
|
Package status provides a status page handler, for exposing a summary of what the various pieces of the agent are doing. |
|
test
|
|
|
Package tracetools provides an abstraction across tracing systems (OpenTelemetry, DataDog).
|
Package tracetools provides an abstraction across tracing systems (OpenTelemetry, DataDog). |
|
Package version provides the agent version strings.
|
Package version provides the agent version strings. |