V4

.buildkite/steps/check-protobuf-generation.sh

@@ -14,6 +14,6 @@ buf generate
 if ! git diff --no-ext-diff --exit-code; then
   echo ^^^ +++
   echo "Generated protobuf files are out of sync with the source code"
-  echo "Please run \`buf generate\` in the internal/proto directory locally, and commit the result."
+  echo "Please run \`buf generate\` in the api/proto directory locally, and commit the result."
   exit 1
 fi

EXPERIMENTS.md

@@ -6,7 +6,7 @@ We frequently introduce new experimental features to the agent. You can use the
 buildkite-agent start --experiment experiment1 --experiment experiment2
 ```
 
-Or you can set them in your [agent configuration file](https://buildkite.com/docs/agent/v3/configuration):
+Or you can set them in your [agent configuration file](https://buildkite.com/docs/agent/v4/configuration):
 
 ```
 experiment="experiment1,experiment2"
@@ -18,25 +18,6 @@ If an experiment doesn't exist, no error will be raised.
 
 ## Available Experiments
 
-### `normalised-upload-paths`
-
-Artifacts found by `buildkite-agent artifact upload` will be uploaded using URI/Unix-style paths, even on Windows. This changes the URLs that artifacts uploaded from Windows agents are stored at, but to one which is URI-compatible.
-
-Artifact names displayed in Buildkite's web UI, as well as in the API, are changed by this.
-
-Take `buildkite-agent artifact upload coverage\report.xml` as an example:
-
-- By default, and without this experiment, this file is uploaded to `s3://example/coverage\report.xml`.
-- With this experiment enabled, it would be `s3://example/coverage/report.xml`.
-
-**Status**: a major improvement for Windows compatibility, we'd like this to be the standard behaviour in 4.0. 👍👍
-
-### `resolve-commit-after-checkout`
-
-After repository checkout, resolve `BUILDKITE_COMMIT` to a commit hash. This makes `BUILDKITE_COMMIT` useful for builds triggered against non-commit-hash refs such as `HEAD`.
-
-**Status**: broadly useful, we'd like this to be the standard behaviour in 4.0. 👍👍
-
 ### `agent-api`
 
 This exposes a local API for interacting with the agent process.
@@ -58,17 +39,6 @@ the PTY to modify the stream. (Or do we? That's why this is an experiment)
 
 **Status:** Experimental for some opt-in testing before being promoted to always-on.
 
-### `override-zero-exit-on-cancel`
-
-If the job is cancelled, and the exit status of the process is 0, it is overridden to be 1 instead.
-
-When cancelling a job, the agent signals the process, which typically causes it to exit with a
-non-zero status code. On Windows this is not true - the process exits with code 0 instead, which
-makes the job appear to be successful. (It successfully exited, no?) By overriding the status to 1,
-a cancelled job should appear as a failure, regardless of the OS the agent is running on.
-
-**Status:** Experimental for some opt-in testing. We hope to promote this to be the default soon™.
-
 ### `interpolation-prefers-runtime-env`
 
 When interpolating the pipeline level environment block, a pipeline level environment variable could take precedence over environment variables depending on the ordering. This may contravene Buildkite's [documentation](https://buildkite.com/docs/pipelines/environment-variables#environment-variable-precedence) that suggests the Job runtime environment takes precedence over that defined by combining environment variables defined in a pipeline.
@@ -77,41 +47,66 @@ We previously made this the default behaviour of the agent (as of v3.63.0) but h
 
 **Status:** Available as an experiment to allow users who have since depended on this behaviour to re-enable it. If you use this feature please let us know so we may better understand your use case.
 
-### `allow-artifact-path-traversal`
-
-Uploaded artifacts include a relative path used by the artifact downloader to download the artifact to a suitable location relative to the destination path. In most circumstances the relative paths generated by `artifact upload` won't contain `..` components, and so will always be downloaded at or inside the destination path.
-
-However, it is possible to upload artifacts using glob patterns containing one or more `..` components, which may be preserved in the artifact path. It is also possible for a user to call the Agent REST API directly in order to upload artifacts with arbitrary paths.
-
-Leaving this experiment disabled prevents `..` components in artifact paths from traversing up from the destination path. Enabling this experiment permits the less-secure behaviour of allowing artifact paths containing `..` to traverse up the destination path.
-
-For example, if an artifact was uploaded with the path `../../foo.txt`, then the command:
-
-```shell
-buildkite-agent artifact download '*.txt' .
-```
-
-has a different effect depending on this experiment:
-
-- With `allow-artifact-path-traversal` disabled, `foo.txt` is downloaded to `./foo.txt`.
-- With `allow-artifact-path-traversal` enabled, `foo.txt` is downloaded to `../../foo.txt`.
-
-**Status:** This experiment is an escape hatch for a security fix. While the new behaviour is more secure, it may break downloading of legitimately-uploaded artifacts.
-
-### `descending-spawn-priority`
-
-When using `--spawn` with `--spawn-with-priority`, the agent assigns ascending priorities to each spawned agent (1, 2, 3, ...). This experiment changes the priorities to be descending (-1, -2, -3, ...) instead. This helps jobs be assigned across all hosts in cases where the value of `--spawn` varies between hosts.
-
-**Status:** Experimental as an escape hatch to default behaviour. Will soon be promoted to a regular flag.
-
-### `propagate-agent-config-vars`
-
-Prepends agent configuration variables (such as `BUILDKITE_GIT_*`, `BUILDKITE_SHELL`, `BUILDKITE_CANCEL_GRACE_PERIOD`, etc.) to the environment file used by the job runner. This is useful in environments like Docker where the agent configuration is not otherwise available to the job process.
-
-**Status:** Experimental while we test the impact on job environments
-
 ### `zip-plugins`
 
 Allows plugins to be downloaded as zip archives instead of being cloned from a Git repository. This is useful for plugins hosted as zip files on HTTP(S) URLs.
 
 **Status:** Experimental while we test zip archive support for plugins.
+
+### `legacy-post-hook-order`
+
+This experiment is an escape hatch that reverts to the v3 execution order of `post-checkout` and `post-command` hooks.
+
+In Agent v3, hooks of any kind would run in the same order as one another (for plugins, the order in which plugins are specified for a step). In v4, multiple `post-checkout`, `post-command`, or `pre-exit` hooks execute in _reverse_ order. This change makes it easier for multiple plugins and hooks to compose.
+
+For example, suppose a step specifies two plugins A and B, and there are also agent and repository hooks. Under version 3, each hook type would execute in the same order:
+
+- agent pre-checkout
+- (pre-checkout is not possible for repository hooks)
+- plugin A pre-checkout
+- plugin B pre-checkout
+- (checkout)
+- agent post-checkout
+- repository post-checkout
+- plugin A post-checkout
+- plugin B post-checkout
+- agent pre-command
+- repository pre-command
+- plugin A pre-command
+- plugin B pre-command
+- (command)
+- agent post-command
+- repository post-command
+- plugin A post-command
+- plugin B post-command
+- agent pre-exit
+- repository pre-exit
+- plugin A pre-exit
+- plugin B pre-exit
+
+Under version 4, the execution order is (key differences in bold):
+
+- agent pre-checkout
+- (pre-checkout is not possible for repository hooks)
+- plugin A pre-checkout
+- plugin B pre-checkout
+- (checkout)
+- plugin **B** post-checkout
+- plugin **A** post-checkout
+- **repository** post-checkout
+- **agent** post-checkout
+- agent pre-command
+- repository pre-command
+- plugin A pre-command
+- plugin B pre-command
+- (command)
+- plugin **B** post-command
+- plugin **A** post-command
+- **repository** post-command
+- **agent** post-command
+- plugin **B** pre-exit
+- plugin **A** pre-exit
+- **repository** pre-exit
+- **agent** pre-exit
+
+**Status:** This escape-hatch experiment will be removed in a future release, once we are confident that it isn't needed.

README.md

@@ -1,7 +1,7 @@
 # Buildkite Agent
 
 ![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)
+[![Go Reference](https://pkg.go.dev/badge/github.com/buildkite/agent/v4.svg)](https://pkg.go.dev/github.com/buildkite/agent/v4)
 
 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
@@ -46,7 +46,7 @@ platforms without extras. On Linux hosts it requires `dbus`.
 
 [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
+[the Buildkite docs](https://buildkite.com/docs/agent/v4/installation). Both
 cover installing the agent with Ubuntu (via apt), Debian (via apt), macOS (via
 homebrew), Windows and Linux.
 
@@ -126,9 +126,11 @@ our Go dependencies. Dependencies are not
 [vendored](https://go.dev/ref/mod#go-mod-vendor) 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.
+The Go module published by this repo (i.e. the one you could use by adding
+`import "github.com/buildkite/agent/v4"` 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
 
@@ -193,12 +195,13 @@ like systems, as well as Windows.
   - Server 2022
 
 [^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.
+[Supported macOS Versions](./docs/macos.md) for the last supported version of
+the Buildkite Agent for versions of macOS prior to those listed above.
 
-[^2]: See [Go's Windows support page](https://go.dev/wiki/Windows) for Go / Windows version
-compatibility and [Supported Windows Versions](./docs/windows.md) for the last supported version
-of the Buildkite Agent for versions of Windows prior to those listed above.
+[^2]: See [Go's Windows support page](https://go.dev/wiki/Windows) for Go /
+Windows version compatibility and [Supported Windows
+Versions](./docs/windows.md) for the last supported version of the Buildkite
+Agent for versions of Windows prior to those listed above.
 
 ## Contributing
 

agent/agent_configuration.go

@@ -53,14 +53,12 @@ type AgentConfiguration struct {
 	VerificationJWKS             any    // The set of keys to verify jobs with
 	VerificationFailureBehaviour string // What to do if job verification fails (one of `block` or `warn`)
 
-	ANSITimestamps               bool
-	TimestampLines               bool
 	HealthCheckAddr              string
 	DisconnectAfterJob           bool
 	DisconnectAfterIdleTimeout   time.Duration
 	DisconnectAfterUptime        time.Duration
-	CancelGracePeriod            int
-	SignalGracePeriod            time.Duration
+	CancelSignalTimeout          time.Duration
+	CancelCleanupTimeout         time.Duration
 	EnableJobLogTmpfile          bool
 	JobLogPath                   string
 	WriteJobLogsToStdout         bool
@@ -73,7 +71,6 @@ type AgentConfiguration struct {
 	TracingBackend               string
 	TracingServiceName           string
 	TracingPropagateTraceparent  bool
-	TraceContextEncoding         string
 	DisableWarningsFor           []string
 	AllowMultipartArtifactUpload bool
 

agent/agent_pool.go

@@ -10,8 +10,8 @@ import (
 	"sync"
 	"time"
 
-	"github.com/buildkite/agent/v3/logger"
-	"github.com/buildkite/agent/v3/status"
+	"github.com/buildkite/agent/v4/logger"
+	"github.com/buildkite/agent/v4/status"
 
 	"github.com/prometheus/client_golang/prometheus/promhttp"
 )

agent/agent_worker.go

@@ -12,12 +12,12 @@ import (
 	"time"
 
 	"connectrpc.com/connect"
-	"github.com/buildkite/agent/v3/api"
-	"github.com/buildkite/agent/v3/core"
-	"github.com/buildkite/agent/v3/internal/process"
-	"github.com/buildkite/agent/v3/logger"
-	"github.com/buildkite/agent/v3/metrics"
-	"github.com/buildkite/agent/v3/status"
+	"github.com/buildkite/agent/v4/api"
+	"github.com/buildkite/agent/v4/core"
+	"github.com/buildkite/agent/v4/internal/process"
+	"github.com/buildkite/agent/v4/logger"
+	"github.com/buildkite/agent/v4/metrics"
+	"github.com/buildkite/agent/v4/status"
 	"github.com/buildkite/roko"
 )
 
@@ -510,13 +510,8 @@ func (a *AgentWorker) RunJob(ctx context.Context, acceptResponse *api.Job, ignor
 	priorityLabel := strconv.Itoa(acceptResponse.Priority)
 	queueLabel := acceptResponse.Env["BUILDKITE_AGENT_META_DATA_QUEUE"]
 
-	// Legacy unlabelled counters; kept incrementing in lockstep with the
-	// labelled counters below so existing scrape consumers see no shape change.
-	jobsStarted.Inc()
-	defer jobsEnded.Inc()
-
-	jobsStartedWithLabels.WithLabelValues(priorityLabel, queueLabel).Inc()
-	defer jobsEndedWithLabels.WithLabelValues(priorityLabel, queueLabel).Inc()
+	jobsStarted.WithLabelValues(priorityLabel, queueLabel).Inc()
+	defer jobsEnded.WithLabelValues(priorityLabel, queueLabel).Inc()
 
 	running := jobsRunning.WithLabelValues(priorityLabel, queueLabel)
 	running.Inc()

agent/agent_worker_action.go

@@ -5,9 +5,9 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/buildkite/agent/v3/api"
-	"github.com/buildkite/agent/v3/internal/ptr"
-	"github.com/buildkite/agent/v3/status"
+	"github.com/buildkite/agent/v4/api"
+	"github.com/buildkite/agent/v4/internal/ptr"
+	"github.com/buildkite/agent/v4/status"
 	"github.com/buildkite/roko"
 )
 

agent/agent_worker_heartbeat.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"time"
 
-	"github.com/buildkite/agent/v3/status"
+	"github.com/buildkite/agent/v4/status"
 )
 
 func (a *AgentWorker) runHeartbeatLoop(ctx context.Context) error {

agent/agent_worker_ping.go

@@ -6,8 +6,8 @@ import (
 	"math/rand/v2"
 	"time"
 
-	"github.com/buildkite/agent/v3/api"
-	"github.com/buildkite/agent/v3/status"
+	"github.com/buildkite/agent/v4/api"
+	"github.com/buildkite/agent/v4/status"
 )
 
 // runPingLoop runs the (classical) loop that pings Buildkite for work.

agent/agent_worker_streaming.go

@@ -7,8 +7,8 @@ import (
 	"time"
 
 	"connectrpc.com/connect"
-	agentedgev1 "github.com/buildkite/agent/v3/api/proto/gen"
-	"github.com/buildkite/agent/v3/status"
+	agentedgev1 "github.com/buildkite/agent/v4/api/proto/gen"
+	"github.com/buildkite/agent/v4/status"
 )
 
 // runStreamingPingLoop runs the streaming loop. It is best-effort

agent/agent_worker_test.go

@@ -18,11 +18,11 @@ import (
 	"time"
 
 	"connectrpc.com/connect"
-	"github.com/buildkite/agent/v3/api"
-	agentedgev1 "github.com/buildkite/agent/v3/api/proto/gen"
-	"github.com/buildkite/agent/v3/core"
-	"github.com/buildkite/agent/v3/logger"
-	"github.com/buildkite/agent/v3/metrics"
+	"github.com/buildkite/agent/v4/api"
+	agentedgev1 "github.com/buildkite/agent/v4/api/proto/gen"
+	"github.com/buildkite/agent/v4/core"
+	"github.com/buildkite/agent/v4/logger"
+	"github.com/buildkite/agent/v4/metrics"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/uuid"
 )

agent/ec2_tags.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"io"
 
-	"github.com/buildkite/agent/v3/internal/awslib"
+	"github.com/buildkite/agent/v4/internal/awslib"
 
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/feature/ec2/imds"

agent/ecs_meta_data.go

@@ -6,7 +6,7 @@ import (
 	"strconv"
 
 	metadata "github.com/brunoscheufler/aws-ecs-metadata-go"
-	"github.com/buildkite/agent/v3/internal/agenthttp"
+	"github.com/buildkite/agent/v4/internal/agenthttp"
 )
 
 type ECSMetadata struct {

agent/fake_api_server_test.go

@@ -12,9 +12,9 @@ import (
 	"time"
 
 	"connectrpc.com/connect"
-	"github.com/buildkite/agent/v3/api"
-	agentedgev1 "github.com/buildkite/agent/v3/api/proto/gen"
-	"github.com/buildkite/agent/v3/api/proto/gen/agentedgev1connect"
+	"github.com/buildkite/agent/v4/api"
+	agentedgev1 "github.com/buildkite/agent/v4/api/proto/gen"
+	"github.com/buildkite/agent/v4/api/proto/gen/agentedgev1connect"
 	"github.com/google/uuid"
 )