The Buildkite Agent’s
annotate command allows you to add additional information to Buildkite build pages using CommonMark Markdown.
On this page:
Creating an annotation
buildkite-agent annotate command creates an annotation associated with the current build.
The first five annotations created will be displayed on the build page, however there is no limit to the amount of annotations you can create. All annotations can be retreived using the GraphQL API.
Options for the
annotate command can be found in the
buildkite-agent cli help:
Usage: buildkite-agent annotate [<body>] [arguments...] Description: Build annotations allow you to customize the Buildkite build interface to show information that may surface from your builds. Some examples include: - Links to artifacts generated by your jobs - Test result summaries - Graphs that include analysis about your codebase - Helpful information for team members about what happened during a build Annotations are written in CommonMark-compliant Markdown, with "GitHub Flavored Markdown" extensions. The annotation body can be supplied as a command line argument, or by piping content into the command. You can update an existing annotation's body by running the annotate command again and provide the same context as the one you want to update. Or if you leave context blank, it will use the default context. You can also update just the style of an existing annotation by omitting the body entirely and providing a new style value. Example: $ buildkite-agent annotate "All tests passed! 🚀" $ cat annotation.md | buildkite-agent annotate --style "warning" $ buildkite-agent annotate --style "success" --context "junit" $ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "success" Options: --context value The context of the annotation used to differentiate this annotation from others [$BUILDKITE_ANNOTATION_CONTEXT] --style success The style of the annotation (success, `info`, `warning` or `error`) [$BUILDKITE_ANNOTATION_STYLE] --append Append to the body of an existing annotation [$BUILDKITE_ANNOTATION_APPEND] --job value Which job should the annotation come from [$BUILDKITE_JOB_ID] --agent-access-token value The access token used to identify the agent [$BUILDKITE_AGENT_ACCESS_TOKEN] --endpoint value The Agent API endpoint (default: "https://agent.buildkite.com/v3") [$BUILDKITE_AGENT_ENDPOINT] --no-http2 Disable HTTP2 when communicating with the Agent API. [$BUILDKITE_NO_HTTP2] --debug-http Enable HTTP debug mode, which dumps all request and response bodies to the log [$BUILDKITE_AGENT_DEBUG_HTTP] --no-color Don't show colors in logging [$BUILDKITE_AGENT_NO_COLOR] --debug Enable debug mode [$BUILDKITE_AGENT_DEBUG]
You can change the visual style of annotations using the
This is an example pipeline showcasing the different styles of annotations:
steps: - label: ":console: Annotation Test" command: | buildkite-agent annotate 'Example `default` style' --context 'ctx-default' buildkite-agent annotate 'Example `info` style' --style 'info' --context 'ctx-info' buildkite-agent annotate 'Example `warning` style' --style 'warning' --context 'ctx-warn' buildkite-agent annotate 'Example `error` style' --style 'error' --context 'ctx-error' buildkite-agent annotate 'Example `success` style' --style 'success' --context 'ctx-success'
Supported Markdown syntax
We use CommonMark with GitHub Flavored Markdown extensions to provide consistent, unambiguous Markdown syntax.
GitHub kindly provide a guide to this syntax.
Annotations do not support GitHub-style syntax highlighting, task lists, user mentions, or automatic links for references to issues, pull requests or commits.
CommonMark supports HTML inside Markdown blocks, but will revert to Markdown parsing on newlines. For more information about how HTML is parsed and which tags CommonMark supports please refer to the CommonMark spec.
Supported CSS Classes
A number of CSS classes are accepted in annotations. These include a subset of layout and formatting controls based on Basscss, and colored console output.
Basscss is a toolkit of composable CSS classes which can be combined to accomplish many styling tasks. We accept the following parts of version 8.0 of Basscss within annotations:
- All except
- All except
- All except Floats (Please use Flexbox instead)
- Type Scale
Colored console output
Console output in annotations can be displayed with ANSI colors when processed through our Terminal tool and wrapped in
<pre class="term"><code></code></pre> tags before uploading.
Embedding & linking artifacts in annotations
Uploaded artifacts can be embedded in annotations by referencing them using the
artifact:// prefix in your image source.
steps: - label: ":console: Annotation Test" command: | buildkite-agent artifact upload "indy.png" cat << EOF | buildkite-agent annotate --style "info" <img src="artifact://indy.png" alt="Belongs in a museum" height=250 /> EOF
You can also link to uploaded artifacts as a shortcut to important files:
steps: - label: "Upload Coverage Report" command: | buildkite-agent artifact upload "coverage/*" cat << EOF | buildkite-agent annotate --style "info" Read the <a href="artifact://coverage/index.html">uploaded coverage report</a> EOF
Using annotations to report test results
Annotations are a great way of rendering test failures that across in different steps in a pipeline.
We've created a plugin to convert all the junit.xml artifacts in a build into a single annotation: https://github.com/buildkite-plugins/junit-annotate-buildkite-plugin
steps: - command: test.sh parallelism: 50 artifact_paths: tmp/junit-*.xml - wait: ~ continue_on_failure: true - plugins: - junit-annotate#v1.2.0: artifacts: tmp/junit-*.xml