> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/registries/manage-registry-metadata.md).

# Manage metadata

Attach custom key-value metadata to registries, artifacts, and versions for searchability, governance, and audit tracking across your account.

Metadata lets you attach custom key-value pairs to registries, artifacts, and versions. Use it to categorize, tag, and track resources according to your organization's workflows, then search or filter on those values later.

## Before you begin

Your role must include **Create/Edit** permission on the registry. Go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md) for details.

## Metadata levels

Metadata applies at three independent levels. Each level is configured separately; there is no inheritance between them, so a key-value pair set on a registry does not carry over to the artifacts or versions inside it.

| Level        | Scope                                      | Typical use                                           |
| ------------ | ------------------------------------------ | ----------------------------------------------------- |
| **Registry** | The entire registry                        | Ownership, environment, or team classification        |
| **Artifact** | A single artifact, across all its versions | Component type, maintainer, documentation links       |
| **Version**  | A single version of an artifact            | Build IDs, commit SHAs, test results, approval status |

{% hint style="info" %}
Version-level metadata is covered in [Add custom metadata to a version](https://developer.harness.io/artifact-registry/3.0/artifacts/artifact-version-details.md#add-custom-metadata-to-a-version). This section covers the registry and artifact levels.
{% endhint %}

## Add metadata to a registry

Registry-level metadata is useful for high-level categorization, such as identifying a registry's purpose, owning team, or environment.

1. In the navigation menu, select **Registries**.
2. Click the registry you want to configure.
3. Select the **Metadata** tab.
4. In the **Custom Metadata** section, click Edit.
5. Enter a key and a value (for example, `owner` and `platform-team`). Click **Add metadata** to add further key-value pairs.
6. Click **Update**.

Registry metadata appears in the registry list and can be used as a filter.

## Add metadata to an artifact

Artifact-level metadata applies across every version of that artifact. Use it for properties that do not change from version to version, such as component type or source repository.

1. In the left navigation, select **Registries**, then open the registry that contains the artifact.
2. Click the artifact you want to configure.
3. Select the **Metadata** tab.
4. Click **Add Property**.
5. Enter a key and a value (for example, `component.type` and `service`).
6. Click **Save**.

Artifact metadata appears on the artifact details page and can be used as a filter within the registry.

## Property limits

* Maximum of 50 key-value pairs per registry, artifact, or version.
* Maximum key length: 128 characters.
* Maximum value length: 256 characters.
* All values are stored as strings. A number or boolean you enter is converted to its string form: `true` becomes `"true"`, `42` becomes `"42"`.
* The same key can be reused with different values across different registries, artifacts, or versions.

## Search and filter by metadata

Metadata filtering is available at four levels:

* **Registry list**: filter registries by metadata on the main registry listing page.
* **Artifact list**: filter artifacts inside a specific registry.
* **Version list**: filter versions of an artifact.
* **Global artifact search**: search across all artifacts using metadata criteria.

Each of these views includes a metadata filter dropdown. Select a key, then choose or enter a value to narrow the list. You can combine multiple metadata filters in the same view.

## Use case examples

These keys and values illustrate common metadata patterns at the artifact and version levels; adapt them to your own naming conventions.

**Artifact-level metadata**

| Key                | Description                | Example value                          |
| ------------------ | -------------------------- | -------------------------------------- |
| `owner`            | Team or person responsible | `platform-team`                        |
| `component.type`   | Type of component          | `service`, `library`, `config`         |
| `security.level`   | Security classification    | `public`, `internal`, `confidential`   |
| `lifecycle.status` | Current lifecycle stage    | `active`, `deprecated`, `experimental` |
| `source.repo`      | Source code repository     | `https://github.com/org/repo`          |

**Version-level metadata**

| Key                    | Description          | Example value                     |
| ---------------------- | -------------------- | --------------------------------- |
| `build.id`             | CI build identifier  | `build-1234`                      |
| `git.commit`           | Git commit hash      | `a1b2c3d4e5f6`                    |
| `approvals.status`     | Approval status      | `pending`, `approved`, `rejected` |
| `security.scan.status` | Security scan result | `passed`, `failed`, `exempted`    |

## Best practices

* Establish naming conventions for metadata keys across your organization before teams start adding their own.
* Use dot notation for related keys, such as `security.level` and `security.scan.status`.
* Keep values well under the 256-character limit for readability in list views.
* Document your metadata schema so keys and expected values stay consistent across registries.
* Review and remove obsolete metadata periodically to keep filters useful.

## Next steps

* [Create a registry](https://developer.harness.io/artifact-registry/3.0/registries/create-a-registry.md) to start adding artifacts and metadata.
* [Add custom metadata to a version](https://developer.harness.io/artifact-registry/3.0/artifacts/artifact-version-details.md#add-custom-metadata-to-a-version) for version-specific tracking.
* [Set artifact filtering rules](https://developer.harness.io/artifact-registry/3.0/registries/set-artifact-filtering-rules.md) to control which artifacts can enter a registry.

{% @harness-feedback/feedback %}
