buildkite-agent job
The buildkite-agent job command provides subcommands for updating or declaring information about the current job.
Updating a job
Use this command in your build scripts to update a job's attributes. Only command jobs can be updated and must not have finished.
Currently, only the timeout_in_minutes attribute can be updated.
timeout_in_minutes (alias timeout): The maximum number of minutes this step is allowed to run, relative to the job's start time. If the job exceeds this time limit, the job is automatically canceled and the build fails. Jobs that time out with an exit status of 0 are marked as passed. See Updating timeouts during a job for more information.
Usage
buildkite-agent job update <attribute> <value> [options...]
Description
Update an attribute of a job. Only command jobs can be updated, and only before they are finished.
Example
$ buildkite-agent job update timeout 20
$ echo 20 | buildkite-agent job update timeout
Options
--no-color #
|
Don't show colors in logging (default: false) |
|---|---|
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` (default: false) |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
--agent-access-token value #
|
The access token used to identify the agent |
--endpoint value #
|
The Agent API endpoint (default: "https://agent-edge.buildkite.com/v3") |
--no-http2 #
|
Disable HTTP2 when communicating with the Agent API (default: false) |
--debug-http #
|
Enable HTTP debug mode, which dumps all request and response bodies to the log (default: false) |
--trace-http #
|
Enable HTTP trace mode, which logs timings for each HTTP request. Timings are logged at the debug level unless a request fails at the network level in which case they are logged at the error level (default: false) |
--job value #
|
The job to update. Defaults to the current job |
--redacted-vars value #
|
Pattern of environment variable names containing sensitive values (default: "*_PASSWORD", "*_SECRET", "*_TOKEN", "*_PRIVATE_KEY", "*_SSH_KEY", "*_ACCESS_KEY", "*_SECRET_KEY", "*_CONNECTION_STRING", "*_API_KEY") |
Promising job failure
Use buildkite-agent job promise-failure in a running command job to declare that the job is expected to fail before the command exits. This lets Buildkite Pipelines signal build failure early while the job continues running and uploading logs, artifacts, and test results. For usage guidance, see Promise job failure.
buildkite-agent job promise-failure 1 --reason "test_failure (2 failed after retries)"
The positional argument is the promised exit status. It must be a positive integer. Exit status 0 is not valid because it promises success rather than failure.
This command requires Buildkite agent version 3.128.0 or later.
Options:
--job |
The job to declare the promised failure for. Defaults to the current job ($BUILDKITE_JOB_ID). |
|---|---|
--reason |
Optional human-readable reason for the promised failure. |
Call this command only once per job, after your script or test runner has confirmed the job should fail. Once the agent has received a successful response for a promised failure, it does not re-send the promise for that job. Submitting the same exit status again is treated as a duplicate and safely ignored (the original declaration stands). Submitting a different exit status for a job that has already declared one is rejected as a conflict (HTTP 409).
Buildkite Pipelines evaluates the promised exit status against retry and soft-fail rules. A promised status that would be retried or soft-failed does not count as a hard failure when the build is marked as failing.