Custom Build Metadata

Announcements
1

Custom Build Metadata is Now Available

Following the Build Metadata and Tags RFC, we’ve shipped custom metadata support for build runs. You can now attach tags and values to your builds, making it easier to filter and categorize your builds.

2026.02.04-custom-build-metadata-detail
2026.02.04-custom-build-metadata-detail2284×1424 207 KB

What’s included

  • Tags: Categorize builds with labels like ci, nightly, or release-candidate
  • Values: Attach key-value pairs to link builds to tickets, PRs, or any external reference
  • Filtering: Find builds by tags and values in the dashboard and via CLI
  • Auto-linking: URLs in values automatically render as clickable links

How to use it

Set environment variables before running your build tuist inspect build:

# Tags (comma-separated)
export TUIST_BUILD_TAGS=ci,nightly,release-candidate

# Key-value pairs (prefix with TUIST_BUILD_VALUE_)
export TUIST_BUILD_VALUE_TICKET=PROJ-1234
export TUIST_BUILD_VALUE_PR=https://github.com/org/repo/pull/123

Then filter builds from the CLI:

tuist build list --tags ci nightly --values ticket=PROJ-1234

Or use the dashboard’s new tag and value filters to find exactly the builds you’re looking for.

API support

If you’re using the API directly, you can pass custom metadata when creating builds:

POST /api/projects/{account}/{project}/runs
{
  "custom_metadata": {
    "tags": ["ci", "nightly"],
    "values": { "ticket": "PROJ-1234", "runner": "macos-14" }
  }
}

And filter builds with query parameters:

GET /api/projects/{account}/{project}/builds?tags=ci&tags=nightly&values=ticket:PROJ-1234

What’s next

We’re exploring how we can better provide teams with the right data, so they can evaluate the health of their projects or the introduction of improvements like the module cache. If you have any ideas for improvements, let us know!

Additionally, check out the Insights documentation for more details.

1 Like