> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/organizing-tests/tags.md). # Tags Label tests, suites, and runs with colored tags. Manage them in Project Settings, assign them from the sidebar or in bulk, and filter lists by tag. A tag is a short colored label you attach to a test, a suite, a test run, or a suite run. Use tags for things that don't fit neatly into a test name or a folder: marking a test as flaky, tracking which version or deployment a run belongs to, or flagging work in progress.
Tests list with colored tags displayed next to test names

Tags shown as colored chips on a test

### What a tag is A tag has a name and a color. The name is a plain string of up to 64 characters, and a colon inside it has no special meaning: `Version:1.23` is just a tag whose name happens to contain a colon, not a key-value pair. Some common ways to use tags: * `flaky` on tests that fail intermittently * `draft` or `in-review` to track where a test stands in your team's workflow * `Version:1.23` to tie a test run to a release * `created-by-ai` to flag tests an agent generated Tag names keep the capitalization you give them, but two tags can't have the same name if you ignore case. Create a tag once, then select it from the picker when assigning tags. Assignments by name through the CLI or Public API use an existing case-insensitive match. {% hint style="success" %} Tags are available on every plan, including Free. Anyone with access to the project can create, assign, and delete tags. {% endhint %} *** ### Managing tags in Project Settings Open **Project Settings → Tags** to see every tag in the project, along with how many tests, suites, test runs, and suite runs use each one.
Project Settings Tags tab listing colored tags and their usage counts

The Tags tab in Project Settings

From this screen you can: * Click **Create tag** and give it a name and a color. * Click **Edit** on a tag to rename it or change its color. * Click **Delete** on a tag you no longer need. A tag's name can be up to 64 characters. Pick its color from the preset palette.
New tag dialog with the preset color palette

Choosing a color from the preset palette

{% hint style="danger" %} **Deleting a tag removes it everywhere.** It disappears from every test, suite, and run it was assigned to, including inherited tags on runs. BugBug shows you how many tests and suites currently use the tag before you confirm, and this action can't be undone. {% endhint %} *** ### Assigning tags to tests and suites Open a test or a suite and look for the **Tags** section in the right sidebar. It lists every tag already assigned as a chip. These are the tags carried directly by the test or suite itself, the ones a run copies when it starts (see [below](#tags-on-test-runs-and-suite-runs)).
Test details sidebar with assigned tags and the tag picker open

The Tags section in a test's sidebar

Click the add button to open the tag picker. From there you can: * Search for an existing tag and assign it. * Remove a tag that's already assigned. * Type a name that doesn't exist yet and create it on the spot. A tag created this way starts with a default color, which you can change later in Project Settings. The picker also has a **Manage tags** shortcut that takes you straight to the Tags tab in Project Settings. Each test or suite can only have a given tag assigned once, so picking a tag that's already there just closes the picker without changing anything. *** ### Tags on test runs and suite runs A run can carry two kinds of tags: * **Inherited tags** - a copy of whatever tags the source test or suite had at the moment the run started. They describe the test or suite, not the run, so they're locked: you can't remove one from the run itself. * **Direct tags** - tags assigned to that specific run. You can add and remove these freely, independently of what the source test or suite has. You can always add more direct tags to a run. What you can't do is remove an inherited one from the run itself. The only way to drop it is to remove the tag from the source test or suite, and even then it only affects runs that start afterward. {% hint style="info" %} Inheritance is a snapshot taken when the run starts, not a live link. Tag a test after a run has already finished, and that run keeps its old tag set. Only the next run picks up the change. {% endhint %} A suite run's sidebar has its own **Tags** section, showing the inherited tags next to a lock icon and any direct tags below them, with the same add and remove controls as a test or suite. Test run details show inherited tags in the details sidebar and let you add or remove direct tags in **Additional run info**.
Suite run sidebar showing suite tags and a directly assigned run tag

Inherited (locked) and direct tags on a suite run

If a tag is added to a run that already inherited it, nothing happens: it stays a single chip instead of becoming a duplicate. *** ### Filtering by tag The Tests, Suites, and Runs history lists have a tag filter, and each tag chip shown in a list row is clickable and sets that filter for you.
Tests list filtered by the Account tag with the tag filter menu open

Filtering the Tests list by tag

Selecting more than one tag narrows the list to items that carry all of the selected tags, not just any one of them. *** ### Bulk actions Select multiple tests, suites, test runs, or suite runs, and choose **Add tags** from the bulk actions menu to assign one or more existing tags to all of them at once. On runs, this adds direct tags; it doesn't touch what each run already inherited. Two current limits worth knowing: * This action only adds tags. To remove a tag from many items at once, open each item individually for now. * You can only pick from tags that already exist in the project. If you need a new tag, create it in Project Settings first. *** ### Cloning and duplicating Tags travel with the item they're on: * Duplicating a test or a suite keeps its tags. * Copying a test to another project copies its tags too, creating matching tag definitions and colors in the target project if they don't already exist there. * Cloning a whole project copies every tag definition, its color, and every assignment. *** ### CLI, API, and YAML #### CLI Add tags to a run when you start it, or set the tags directly on a test or suite: ```bash bugbug tests run --tag "Version:1.23" --tag flaky bugbug tests tags set --tag flaky --tag draft ``` `--tag` can be repeated. Setting tags replaces the current set; omitting `--tag` clears it. See the [CLI tag commands](/integrations/cli.md#tags) for suites and runs too. #### Public API Use the API v2 tags endpoint to replace a test's direct tags: ```bash curl -X PUT \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ -d '{"tags": ["flaky", "Version:1.23"]}' \ "https://api.bugbug.io/v2/tests//tags/" ``` The same pattern applies to suites and runs. Updating a run changes only its direct tags; inherited tags stay intact. Assigning a tag by a new name creates it with the default color. Tags can also be used to filter API results. See the generated [Swagger](https://app.bugbug.io/docs/swagger/?version=v2) or [Redoc](https://app.bugbug.io/docs/redoc/?version=v2) reference for current endpoints, filters, and request fields. #### YAML Project exports define tag names and colors; test and suite files list the tags assigned to that item: ```yaml schema_version: '1.0' schema_type: project data: tags: - name: flaky color: '#D1242F' ``` ```yaml schema_version: '1.0' schema_type: test data: tags: - flaky ``` Importing a standalone test or suite creates any missing tags with the default color. See the [YAML tag schema](/export-import-and-backup/yaml-schema.md#tags) for import behavior and complete examples. ### Frequently asked questions
Can I tag components? Not yet. This first version of tags covers tests, suites, test runs, and suite runs.
Does deleting a tag delete the tests, suites, or runs it was on? No. Deleting a tag only removes the label. The tests, suites, and runs themselves are untouched.
Why can't I create "high" when a "High" tag already exists? Tag names are case-insensitive for uniqueness, so BugBug rejects the duplicate. Select the existing `High` tag when assigning tags instead. CLI and Public API name-based assignments use the existing tag automatically.
Can two projects use the same tag? Yes. Tags are scoped to a project, so two projects can each have their own `smoke` tag. If you copy a test or clone a project, matching tags are created or reused in the destination automatically.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bugbug.io/organizing-tests/tags.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.