> 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/reference/rbac-and-permissions.md).

# RBAC: roles, permissions, and scopes

Reference for Artifact Registry roles and permissions, covering built-in roles, permission actions, scope rules, and pipeline access constraints.

Artifact Registry uses the Harness role-based access control (RBAC) model. Access is controlled by combining a **role** (what someone can do) with a **resource group** (which registries they can do it on) and assigning that combination to a **principal** (a user, user group, or service account) at a specific **scope** (account, org, or project).

Go to [Harness platform RBAC](https://developer.harness.io/harness-platform/use-harness-platform/platform-access-control) for the full platform-level model. This page covers what is specific to Artifact Registry: built-in roles, the permissions they grant, scope rules that affect pipeline access, and common assignment patterns.

## Built-in roles

Artifact Registry ships with three built-in roles. Assign them at the scope where the registry lives.

| Role            | What it allows                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Viewer**      | View registry configuration; download (pull) artifacts                                                                    |
| **Contributor** | Everything in Viewer, plus upload (push) artifacts                                                                        |
| **Admin**       | Everything in Contributor, plus create and edit registries, delete registries, delete artifacts, and quarantine artifacts |

{% hint style="info" %}
Built-in roles cannot be edited. To create a role with a custom permission set, go to **Account Settings** (or Org/Project Settings) > **Access Control** > **Roles** > **New Role**.
{% endhint %}

***

## Permissions reference

All Artifact Registry permissions belong to the **Artifact Registry** resource under the **Artifact Management** module.

| Permission                                | Action          | Description                                                                                  |
| ----------------------------------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `artifact_artregistry_view`               | View            | View registry details, configuration, and artifact lists. Required for all other operations. |
| `artifact_artregistry_edit`               | Create / Edit   | Create a new registry or edit an existing registry's configuration.                          |
| `artifact_artregistry_delete`             | Delete Registry | Permanently delete a registry and all its artifacts.                                         |
| `artifact_artregistry_uploadartifact`     | Upload (push)   | Push an artifact or image to the registry.                                                   |
| `artifact_artregistry_downloadartifact`   | Download (pull) | Pull an artifact or image from the registry.                                                 |
| `artifact_artregistry_deleteartifact`     | Delete Artifact | Delete a specific artifact version from the registry.                                        |
| `artifact_artregistry_quarantineartifact` | Quarantine      | Place an artifact version in quarantine or release it.                                       |

### Firewall Exceptions permission

The **Firewall Exceptions** resource has a separate permission, also under the Artifact Management module:

| Permission                            | Action  | Description                                                                             |
| ------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `artifact_firewallexceptions_approve` | Approve | Approve or reject a request to exempt an artifact from a Dependency Firewall violation. |

Go to [Manage exceptions](https://developer.harness.io/artifact-registry/3.0/dependency-firewall/manage-exceptions.md) for the exception review workflow.

### Role-to-permission mapping

| Permission             | Viewer | Contributor | Admin |
| ---------------------- | ------ | ----------- | ----- |
| View                   | ✓      | ✓           | ✓     |
| Download               | ✓      | ✓           | ✓     |
| Upload                 |        | ✓           | ✓     |
| Create / Edit registry |        |             | ✓     |
| Delete registry        |        |             | ✓     |
| Delete artifact        |        |             | ✓     |
| Quarantine artifact    |        |             | ✓     |

***

## Scope and pipeline access

### Scope hierarchy

Registries are created at account, org, or project scope. Permissions are inherited downward; a role assigned at the account scope covers registries at all org and project scopes within it. The reverse is not true: a project-scoped role does not grant access to registries in a parent scope.

| Scope   | Registry is accessible from          |
| ------- | ------------------------------------ |
| Account | All orgs and projects in the account |
| Org     | All projects within the org          |
| Project | That project only                    |

### Pipeline access constraints

A pipeline running inside a project can push to and pull from registries in its **own project** and in **parent scopes** (org and account). It cannot access registries in **sibling projects**, even if the executing principal has permissions on those registries.

{% hint style="warning" %}
If multiple projects need to share artifacts, create the registry at the **org** or **account** scope. Creating it at a project scope and trying to reference it from another project will fail with a 403 at runtime.
{% endhint %}

### Registry name uniqueness

Registry identifiers are globally unique across your entire Harness account, regardless of scope. You cannot have two registries named `docker-prod` at different scopes; the name must be unique account-wide.

***

## Assign roles

Assign a role in the Harness UI:

1. Go to **Account Settings** (or **Org Settings** / **Project Settings**, depending on the scope where the registry lives).
2. Select **Access Control**.
3. Select the **Users**, **User Groups**, or **Service Accounts** tab.
4. Find the principal and select **Manage Roles**.
5. Select **Add**, choose the role (Viewer, Contributor, or Admin), and select a resource group.
6. Save.

For a resource group that covers only specific registries, select **Named Resources** and add the registry identifiers individually. For broad access, use **All Resources** of type Artifact Registry.

***

## Service accounts for automation

CI/CD pipelines, the Harness CLI, and automation tools should authenticate using a **service account** rather than a personal user account.

A service account token does not expire with a user's session and can be scoped to exactly the permissions the pipeline needs.

**Recommended setup for a CI pipeline that only pushes artifacts**:

1. Create a service account under **Project Settings > Access Control > Service Accounts**.
2. Generate an API key and token for the service account.
3. Assign the **Contributor** role scoped to the target registry (or the entire project if the pipeline pushes to multiple registries).
4. Set the token as a secret in the pipeline (`$HARNESS_API_KEY`).

**Recommended setup for a read-only deployment pipeline**:

1. Create a separate service account for the deployment stage.
2. Assign the **Viewer** role.
3. Use a resource group that covers only the registries the deployment stage needs to pull from.

{% hint style="info" %}
Using separate service accounts for push and pull operations limits the blast radius if a token is compromised; a leaked deploy token cannot be used to overwrite artifacts.
{% endhint %}

***

## Common role assignment patterns

### Read-only access for auditors or external consumers

Assign the **Viewer** role with a resource group that covers all registries at the appropriate scope. The principal can browse artifact lists, view registry configuration, and pull artifacts, but cannot push or modify anything.

```
Principal:      audit-team (User Group)
Role:           Viewer
Resource Group: All Artifact Registries (Account)
Scope:          Account
```

### CI pipeline: push only

A build pipeline needs to push artifacts but should not be able to modify registry configuration or delete artifacts.

```
Principal:      ci-service-account (Service Account)
Role:           Contributor
Resource Group: Named, build-artifacts (Project)
Scope:          Project
```

### Platform team: registry administration

A platform team manages the registries but individual developers should not be able to delete them.

```
Principal:      platform-team (User Group)
Role:           Admin
Resource Group: All Artifact Registries (Org)
Scope:          Org
```

### Dependency Firewall exception approver

A security engineer needs to review and approve exception requests when the Dependency Firewall blocks a package. This requires only the Firewall Exceptions permission, not full Admin on the registry.

```
Principal:      security-team (User Group)
Role:           Custom role with artifact_firewallexceptions_approve
Resource Group: All Artifact Registries (Account)
Scope:          Account
```

***

## Troubleshooting

<details>

<summary>403 when pushing from a pipeline</summary>

The service account or user running the pipeline does not have the `artifact_artregistry_uploadartifact` permission on the target registry. Verify:

1. The principal has Contributor or Admin role assigned.
2. The resource group covers the registry (not "All Resources" at a child scope).
3. The registry scope is reachable from the pipeline's project; a pipeline cannot reach sibling-project registries. If needed, move the registry to org or account scope.

</details>

<details>

<summary>403 when pulling from a pipeline</summary>

The service account or user running the pipeline does not have the `artifact_artregistry_downloadartifact` permission. Assign the Viewer role at minimum. Also confirm the registry is at the same scope as the pipeline or a parent scope; it cannot be in a sibling project.

</details>

<details>

<summary>403 when creating a registry</summary>

Creating a registry requires `artifact_artregistry_edit`. The Viewer and Contributor roles do not include this permission. Assign the Admin role, or create a custom role that includes `artifact_artregistry_edit`.

</details>

<details>

<summary>Identity token expired, 401 during push or pull</summary>

Identity tokens (generated from Setup Client) expire after the duration selected at creation. Regenerate the token from the registry's **Setup Client** menu. For CI pipelines, use a service account API key instead, which persists until manually revoked.

</details>

<details>

<summary>A user can view registries they should not see</summary>

Check whether the user is a member of a user group that has account- or org-scoped Viewer access. RBAC is additive; access from any assignment applies. Narrow the resource group to named resources if you need to restrict visibility to specific registries.

</details>

## Next steps

* [Harness platform RBAC](https://developer.harness.io/harness-platform/use-harness-platform/platform-access-control)
* [Permissions reference](https://developer.harness.io/harness-platform/use-harness-platform/platform-access-control/permissions-reference)
* [Manage exceptions](https://developer.harness.io/artifact-registry/3.0/dependency-firewall/manage-exceptions.md)
* [Authentication and identity tokens](https://developer.harness.io/artifact-registry/3.0/concepts/authentication-and-identity-tokens.md)
* [CLI reference](https://developer.harness.io/artifact-registry/3.0/reference/cli.md)

{% @harness-feedback/feedback %}
