> 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/troubleshooting-and-resources/ar-best-practices.md).

# Best Practices

Harness Artifact Registry provides centralized management for Docker, Helm, Maven, NPM, Python, and other artifact types. This guide outlines **naming conventions**, **scope selection**, and **governance strategies** to help you build a scalable registry structure.

### Why naming matters <a href="#why-naming-matters" id="why-naming-matters"></a>

Registry names must be globally unique across your Harness account, regardless of scope (account, org, or project). **Reusing names like `docker-dev` in multiple scopes is not allowed**.

Registry IDs are unique at the account level, but pipeline push and pull access follows the Harness scope hierarchy. A pipeline can push to or pull from registries in its **current project** and in **parent scopes** (organization and account). A pipeline **cannot** push to or pull from registries in **sibling projects**, even when the executing principal has permissions on those registries.

{% hint style="info" %}
**NAMING AND SCOPING BENEFITS**

Follow consistent naming and scoping practices to avoid registry sprawl and support better collaboration, access control, and automation. Place registries that multiple projects must share at the organization or account level.
{% endhint %}

***

### Before you create a registry <a href="#before-you-create-a-registry" id="before-you-create-a-registry"></a>

Use this checklist to guide naming, scope, and ownership decisions before creating a new artifact registry.

1. **Can you reuse an existing registry?**
2. **Do you need an upstream proxy?**
3. **Do you know what scope is appropriate for your use case?**
4. **Who will own and manage the registry?**

Once you've answered these questions, continue reading to define a registry name and scope that fits your needs.

***

### Recommended naming convention <a href="#recommended-naming-convention" id="recommended-naming-convention"></a>

Use this format to ensure global uniqueness and clarity: `<scope>-<team>-<package-type>-<environment>`

#### Naming components <a href="#naming-components" id="naming-components"></a>

| Component                  | Values / Examples                                                | Description                               |
| -------------------------- | ---------------------------------------------------------------- | ----------------------------------------- |
| **Scope Indicator**        | `acct`, `org`, `proj`                                            | Registry scope: account, org, or project. |
| **Team Indicator**         | `platform`, `mobile`, `backend`, `frontend`, `data`              | Indicates the owning or producing team.   |
| **Package Type**           | `docker`, `helm`, `maven`, `npm`, `python`, `proxy`, `artifacts` | Type of artifact the registry stores.     |
| **Environment (optional)** | `dev`, `test`, `prod`                                            | Indicates artifact lifecycle stage.       |

✅ **Good Examples**

* `acct-platform-docker-dev`
* `org-backend-maven-prod`
* `proj-mobile-npm-test`

❌ **Avoid**

* `docker-dev` (no scope/team context)
* `api`, `frontend`, `backend` (too generic)
* `proj-frontend-user-dashboard-components-npm-dev` (overly long)

{% hint style="info" %}
**REGISTRY NAME**

Your registry name must start with a letter and can only contain lowercase alphanumerics, `_`, `.` and `-`, and **must be unique to your Harness Account**.
{% endhint %}

***

### Scope strategy <a href="#scope-strategy" id="scope-strategy"></a>

| Scope            | Use For                                         | Managed By      |
| ---------------- | ----------------------------------------------- | --------------- |
| **Account**      | Shared tools, base images, proxies              | Platform/DevOps |
| **Organization** | Team-shared libraries, internal components      | Team Leads      |
| **Project**      | Environment-specific or service-specific builds | Dev Teams       |

A pipeline can use registries in its current project and in parent scopes only. Place shared artifacts at the organization or account level. If you create a registry in one project, pipelines in sibling projects cannot push to or pull from it.

***

### Registry URL format <a href="#registry-url-format" id="registry-url-format"></a>

* **Docker:** `pkg.harness.io/<account-id>/<registry-name>/<artifact>:<tag>`
* **Other types:** `pkg.harness.io/pkg/<account-id>/<registry-name>/<package-type>/`

> Ensure `<account-id>` is lowercase and matches the format used in your account settings.

***

### Upstream proxy best practices <a href="#upstream-proxy-best-practices" id="upstream-proxy-best-practices"></a>

Use upstream proxies at **account or org level** to:

* Cache external sources like Docker Hub, Maven Central, PyPI.
* Improve performance and reliability.
* Apply centralized scanning policies.

{% hint style="info" %}
**UPSTREAM PROXY USAGE**

The upstream proxy is essential for caching open-source dependencies. During a build, if a required dependency is not already cached, it is retrieved from a public repository and stored in the Upstream Proxy artifact tab. This ensures continuous availability, even if the source repository (e.g. Docker Hub or Maven Central) experiences downtime. Harness’s caching mechanism enhances reliability and efficiency by reducing dependency on external services and safeguarding access to critical artifacts.
{% endhint %}

#### Proxy registry name guidance <a href="#proxy-registry-name-guidance" id="proxy-registry-name-guidance"></a>

* For account-wide proxies, a team name is **not** required in the registry name.
* Including `proxy` in the registry name (e.g., `acct-docker-proxy-dev`) is helpful for clarity and governance.
* You do **not** need a separate proxy for each environment.
* Example: `acct-docker-proxy-dev`

### Governance and ownership <a href="#governance-and-ownership" id="governance-and-ownership"></a>

Define roles and responsibilities:

* **Registry Admin**: Full access + user permissions.
* **Contributor**: Push/pull access.
* **Viewer**: Read-only access.

***

### Planning ahead <a href="#planning-ahead" id="planning-ahead"></a>

* Inventory teams and artifact types.
* Align naming with scope and lifecycle.
* Reserve namespace for known future needs.
* Set documentation and approval standards.

***

By following these best practices, you'll ensure your artifact registry is secure, organized, and ready to scale with your team's needs.

### Next steps <a href="#next-steps" id="next-steps"></a>

* [Get Started with Artifact Registry](/artifact-registry/3.0/new-to-artifact-registry/quickstart.md)
* [Integrate with your CD pipelines](/artifact-registry/3.0/use-artifact-registry/platform-integrations/cd-ar-integrations.md)
* [Learn about security integrations](/artifact-registry/3.0/use-artifact-registry/platform-integrations/security-integrations/ssd-ar-integrations.md)
* [Automate actions with Webhooks](/artifact-registry/3.0/use-artifact-registry/manage-registries/ar-webhooks.md)