# Tags and flag discovery

Build an organisation-wide vocabulary for finding and reviewing related flags.

Tags are organisation-owned labels attached to flags. They help people find related controls across
projects without changing runtime evaluation.

Use tags for recurring discovery questions such as ownership area, product surface, initiative, or
service. Do not duplicate lifecycle and runtime state that FeatureGate already models directly.

## Build a useful vocabulary

A small governed vocabulary is more useful than many near-duplicates.

| Good tag         | Question it answers                    |
| ---------------- | -------------------------------------- |
| `checkout`       | Which flags affect checkout?           |
| `identity`       | Which flags belong to identity work?   |
| `mobile`         | Which flags affect the mobile surface? |
| `search-service` | Which service owns these controls?     |

Avoid tags such as `active`, `urgent`, `production`, or `cleanup-due`. Status, environment, intent,
and cleanup signals already answer those questions and remain accurate automatically.

Avoid employee names and raw customer names. Use stable team or account references only when the
organisation has approved that taxonomy and understands its privacy implications.

## Create and attach tags

Tags can be created inline during flag creation and editing. A flag can carry several tags. Tags with
no remaining flags disappear from the active vocabulary.

Use the same spelling and granularity across projects. Before creating a new label, search for an
existing synonym such as `payments` versus `billing`.

Members, admins, and owners can manage flag tags as part of normal project building. Viewers can use
tags for discovery but cannot mutate them.

## Search and filter

Free-text flag search matches tag labels as well as flag identity. Project flag lists can filter by
one organisation tag key at a time.

Combine tags with dedicated filters. For example:

- `checkout` plus **Cleanup due** finds temporary debt in one product area.
- `identity` plus **Partial rollout** finds releases needing an owner decision.
- `search-service` plus archived discovery helps verify code cleanup.

Do not encode several dimensions into one label such as `checkout-production-cleanup`. Use one stable
area tag and let environment and lifecycle filters provide the changing state.

## Runtime boundary

Tags are console metadata. They are not included in evaluation, snapshots, invalidation, or the
public Management API preview.

Adding, removing, or renaming a tag cannot change a flag value or refresh an SDK. Automation that
needs tags is not currently supported by the public Management API.

## Maintain the vocabulary

Review tags during cleanup work or organisation ownership changes:

1. Identify near-duplicates and spelling variants.
2. Choose the surviving organisation term.
3. Retag affected flags.
4. Confirm search and saved operational habits still work.
5. Allow unused tags to disappear.

Document a small set of preferred area tags for larger teams. Avoid building a deep taxonomy that
requires constant administration.

## Common problems

- **A tag is missing:** it may have no remaining flags.
- **Search returns too much:** use a tag filter with lifecycle or status filters.
- **A runtime value did not change:** tags never participate in evaluation.
- **Automation cannot attach a tag:** the current Management API preview does not expose that workflow.

Related pages: [Flag lifecycle and intent](/docs/flags/lifecycle-and-intent),
[Review and clean up flags](/docs/operate/review-and-clean-up-flags), and
[Activity and audit history](/docs/operate/activity-and-audit).