Links & images in log output

You can embed links, external images, and images generated by your builds directly into your logs using special ANSI escape codes.

ANSI escape codes are used for many tasks in UNIX terminals, such as setting text color uses an ANSI escape code. Buildkite supports most standard ANSI escape codes and a few special ones, thanks to our terminal output processor, terminal-to-html.

Links

You can embed clickable links to Buildkite or other web pages by using ANSI escape code 1339.

The following Bash function takes a URL and optional link text and will output the correct escape code sequence:

function inline_link {
  LINK=$(printf "url='%s'" "$1")

  if [ $# -gt 1 ]; then
    LINK=$(printf "%s;content='%s'" "$LINK" "$2")
  fi

  printf '\033]1339;%s\a\n' "$LINK"
}

You can use it like so:

inline_link 'https://buildkite.com/'

Or, to use a custom label:

inline_link 'https://buildkite.com/' 'Buildkite'

You can also link to an uploaded artifact by using the artifact:// URL syntax:

inline_link 'artifact://tmp/images/omg.gif'

Images

Syntax for inlining images

The syntax for inlining images uses ANSI escape code 1338. A url is required, and you can optionally specify an alt attribute to describe what the image is.

The following Bash function takes an image URL and alternative text and will output the correct escape code sequence:

function inline_image {
  printf '\033]1338;url='"$1"';alt='"$2"'\a\n'
}

You can use it like so:

inline_image 'https://media0.giphy.com/media/8Ry7iAVwKBQpG/giphy.gif' 'Rainbows'

When rendered in Buildkite (using our open-source Terminal tool) it will look like this:

When you run the script locally you won't see any output because your terminal will ignore the escape code. If you pipe your build script to more you can see the raw escape codes.

Inlining build artifact images

You can inline artifact images by using the artifact:// URL syntax. For example you can inline the following artifact:

by using the following URL:

inline_image 'artifact://tmp/images/omg.gif' 'OMG'

Be careful to ensure the part of the URL after artifact:// exactly matches the path you see in the Artifacts tab (for example, it can't have a preceding ./).

The image artifact does not have to be uploaded at the time it's written to the build log. If the artifact has not been uploaded you'll see a loading placeholder, and as soon as it's ready the image will automatically appear.

If you are using private artifacts, your images need to be base64-encoded so that Buildkite can access and inline them.

Base64-encoded images

If you want to embed an image encoded in base64, you can use iTerm's image format, but be mindful of the log output limits. Unless you're embedding images for a specific reason, it's better to upload the image as a build artifact and reference it using the artifact:// URL.

Library support

The capybara-inline-screenshot Ruby gem will automatically inline screenshots of your integration test failures and also supports the iTerm image format for viewing failures directly in your terminal. When run under CI it automatically uses the artifact:// URL format.