Skip to content

Commit

Permalink
Merge pull request #2354 from buildkite/fix-readme-supported-os-versions
Browse files Browse the repository at this point in the history 
README and macOS versions update
  • Loading branch information
@DrJosh9000
DrJosh9000 authored Sep 7, 2023
2 parents 8163ea9 + a000dc5 commit 9c6cff0
Show file tree
Hide file tree
Showing 2 changed files with 124 additions and 71 deletions.
157 changes: 98 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,115 +1,143 @@
# Buildkite Agent

[![Build status](https://badge.buildkite.com/08e4e12a0a1e478f0994eb1e8d51822c5c74d395.svg?branch=main)]()
![Build status](https://badge.buildkite.com/08e4e12a0a1e478f0994eb1e8d51822c5c74d395.svg?branch=main)
[![Go Reference](https://pkg.go.dev/badge/github.com/buildkite/agent/v3.svg)](https://pkg.go.dev/github.com/buildkite/agent/v3)

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](https://buildkite.com/) for work, running build jobs, reporting back the status code and output log of the job, and uploading the job's artifacts.
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](https://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](https://buildkite.com/docs/agent)
Full documentation is available at
[buildkite.com/docs/agent](https://buildkite.com/docs/agent).

```
```text
$ buildkite-agent --help
Usage:
buildkite-agent <command> [options...]
Available commands are:
start Starts a Buildkite agent
annotate Annotate the build page within the Buildkite UI with text from within a Buildkite job
artifact Upload/download artifacts from Buildkite jobs
meta-data Get/set data from Buildkite jobs
pipeline Make changes to the pipeline of the currently running build
step Make changes to a step (this includes any jobs that were created from the step)
bootstrap Run a Buildkite job locally
help Shows a list of commands or help for one command
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`.
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](https://buildkite.com/organizations/-/agents) on Buildkite has personalised instructions, or you can refer to [the Buildkite docs](https://buildkite.com/docs/agent/v3/installation). Both cover installing the agent with Ubuntu (via apt), Debian (via apt), macOS (via homebrew), Windows and Linux.
[The agents page](https://buildkite.com/organizations/-/agents) on Buildkite has
personalised instructions, or you can refer to
[the Buildkite docs](https://buildkite.com/docs/agent/v3/installation). 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](https://hub.docker.com/r/buildkite/agent) for the
following operating systems. Docker images are tagged using the agent SemVer components followed
by the operating system.
We also support and publish
[Docker Images](https://hub.docker.com/r/buildkite/agent) for the following
operating systems. Docker images are tagged using the agent SemVer components
followed by the operating system.

For example, agent version 3.30.0 is published as:
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.30-ubuntu-20.04, tracks bugfix updates in version 3.30 installed in Ubuntu 20.04
- 3.30.0-ubuntu-20.04, tracks the exact version installed in Ubuntu 20.04
- 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.12
- Ubuntu 18.04 LTS (x86_64), supported to end of life for 18.04
- Ubuntu 20.04 LTS (x86_64), supported to end of life for 20.04
- Ubuntu 22.04 LTS (x86_64), supported to end of life for 22.04
- 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.
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:

```bash
buildkite-agent start --token
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. A full list of the features that we track can be found [here](https://github.com/buildkite/agent/blob/03aec39f97fe7d20936e6af63cd793a87fac2c19/clicommand/agent_start.go#L135).
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](https://github.com/search?q=repo%3Abuildkite%2Fagent+language%3Ago+symbol%3AAgentStartConfig.Features+&type=code).

## Development

These instructions assume you are running a recent macOS, but could easily be adapted to Linux and Windows.
These instructions assume you are running a recent macOS, but could easily be
adapted to Linux and Windows.

```bash
# Make sure you have go 1.11+ installed.
# Make sure you have Go installed.
brew install go

# Download the code somewhere, no GOPATH required
# Download the code somewhere - no GOPATH required.
git clone https://github.com/buildkite/agent.git
cd agent

# Create a temporary builds directory
# Create a temporary builds directory.
mkdir /tmp/buildkite-builds

# Build an agent binary and start the agent
# 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
# Or, run the agent directly and skip the build step.
go run *.go start --debug --build-path=/tmp/buildkite-builds --token "abc"
```

### Dependency management

We're using Go 1.18+ and [Go Modules](https://github.com/golang/go/wiki/Modules) to manage our Go dependencies.
### Go Version and Dependency Management

Dependencies are no longer committed to the repository, so compiling on Go <= 1.10 is not supported.
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.

### Go Version

The agent is compiled using Go 1.18. Previous go versions may work, but are not guaranteed to.
We're using [Go Modules](https://github.com/golang/go/wiki/Modules) to manage
our Go dependencies. Dependencies are not
[vendored](https://go.dev/ref/mod#go-mod-vendor) into the repository unless
necessary.

## Platform Support

We provide support for security and bug fixes on the current major release only.
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 golang
itself [supports](https://github.com/golang/go/wiki/MinimumRequirements).
Our architecture and operating system support is primarily limited by
[what Go itself supports](https://github.com/golang/go/wiki/MinimumRequirements).

### Architecture Support

We offer support for the following machine architectures (inspired by the Rust language platform
support guidance).
We offer support for the following machine architectures (inspired by the Rust
language platform support guidance).

#### Tier 1, guaranteed to work

Expand All @@ -126,13 +154,19 @@ support guidance).

#### Tier 3, community supported

We release binaries for various other platforms, and it should be possible to build it anywhere Go compiles, but official support is not provided for these Tier 3 platforms.
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 major releases may drop support for old operating systems. The agent
binary is fairly portable and should run out of the box on most UNIX like systems.
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
Expand All @@ -142,17 +176,19 @@ binary is fairly portable and should run out of the box on most UNIX like system
- CentOS 8
- Amazon Linux 2
- macOS [^1]
- 10.12
- 10.13
- 10.14
- 10.15
- 11
- 10.13 (High Sierra)
- 10.14 (Mojave)
- 10.15 (Catalina)
- 11 (Big Sur)
- 12 (Monterey)
- 13 (Ventura)
- Windows Server
- 2012
- 2012 R2
- 2016
- 2019
- 2022

[^1]: See https://github.com/golang/go/issues/23011 for macOS / golang support and
[^1]: See https://github.com/golang/go/issues/23011 for macOS / Go support and
[Supported macOS Versions](./docs/macos.md) for the last supported version of the
Buildkite Agent for versions of macOS prior to those listed above.

Expand All @@ -162,8 +198,11 @@ See [./CONTRIBUTING.md](./CONTRIBUTING.md)

## Contributors

Many thanks to our fine contributors! A full list can be found [here](https://github.com/buildkite/agent/graphs/contributors), but you're all amazing, and we greatly appreciate your input ❤️
Many thanks to
[our fine contributors](https://github.com/buildkite/agent/graphs/contributors)!
You're all amazing, and we greatly appreciate your input ❤️

## Copyright

Copyright (c) 2014-2019 Buildkite Pty Ltd. See [LICENSE](./LICENSE.txt) for details.
Copyright (c) 2014-2023 Buildkite Pty Ltd.
See [LICENSE](./LICENSE.txt) for details.
38 changes: 26 additions & 12 deletions docs/macos.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,28 @@
# Supported macOS versions

macOS Version | Last Supported By Golang | Last Supported Agent Version
--- | --- | ---
10.8 | 1.10.8 | v3.5.4
10.9 | 1.10.8 | v3.5.4
10.10 | 1.13 | v3.20.0
10.11 | 1.15 | v3.27.0
10.12 | 1.16 |
10.13 | 1.17 TBC |
10.14 | |
10.15 | |
11 | |
12 | |
macOS version | Last Go version to support | Last Agent version to support
---------------------- | -------------------------- | -----------------------------
10.8 (Mountain Lion) | [1.10][go110] | [v3.5.4][agent354]
10.9 (Mavericks) | [1.10][go110] | [v3.5.4][agent354]
10.10 (Yosemite) | [1.12][go112] | [v3.15.2][agent3152]
10.11 (El Capitan) | [1.14][go114] | [v3.25.0][agent3250]
10.12 (Sierra) | [1.16][go116] | [v3.33.3][agent3333]
10.13 (High Sierra) | [1.20][go120] | [Latest release][latest]
10.14 (Mojave) | [1.20][go120] | [Latest release][latest]
10.15 (Catalina) | TBC | [Latest release][latest]
11 (Big Sur) | TBC | [Latest release][latest]
12 (Monterey) | TBC | [Latest release][latest]
13 (Ventura) | TBC | [Latest release][latest]
14 (Sonoma) | TBC | Coming soon!

[go110]: https://go.dev/doc/go1.10#ports
[go112]: https://go.dev/doc/go1.12#darwin
[go114]: https://go.dev/doc/go1.14#darwin
[go116]: https://go.dev/doc/go1.16#darwin
[go120]: https://go.dev/doc/go1.20#darwin

[agent354]: https://github.com/buildkite/agent/releases/tag/v3.5.4
[agent3152]: https://github.com/buildkite/agent/releases/tag/v3.15.2
[agent3250]: https://github.com/buildkite/agent/releases/tag/v3.25.0
[agent3333]: https://github.com/buildkite/agent/releases/tag/v3.33.3
[latest]: https://github.com/buildkite/agent/releases/

0 comments on commit 9c6cff0

Please sign in to comment.