> 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/release-orchestration/use-release-orchestration/release-orchestration-execution/permissions-and-pipeline-identity.md).
# Process and activity permissions and pipeline identity
Control who can create, view, edit, delete, and run releases, processes, and activities, and choose which identity runs pipelines from a release.
Release Orchestration lets you grant permissions on releases, processes, and activities separately, so you can give a team the ability to author processes without letting it run releases, or let operators run releases without editing the activities inside them. A second setting controls who runs a Harness pipeline when a release reaches a pipeline activity: either the person who started the release or the Release Management service.
Use this topic to set up granular permissions, migrate existing custom roles, and decide how pipelines authenticate when a release runs them.
## What you will learn from this topic
By the end of this topic, you will be able to:
* How to grant [Create, View, Edit, Delete, and Execute permissions](#permissions-for-releases-activities-and-processes) for releases, activities, and processes.
* How to find the [required permissions by action](#required-permissions-by-action) for a release or a process, and understand the [activity execute permission validation](#activity-execute-permission-validation) that applies to the release initiator.
* How to [migrate existing custom roles](#migrate-existing-custom-roles) that have **Releases** permissions to the new permissions.
* How to choose the [pipeline identity](#pipeline-identity) that runs a pipeline activity, either the release initiator or only the Release Management service.
* [Troubleshoot](#troubleshooting) a release or pipeline execution that fails because of permissions.
## Before you begin
Before you configure permissions for Release Orchestration, make sure you have the following:
* **Access Control permissions**: Permission to create and edit roles and role bindings at the scope you manage. Go to [Permissions reference](https://developer.harness.io/harness-platform/use-harness-platform/platform-access-control/permissions-reference) to review how Harness permissions work.
* **Release Orchestration concepts**: Understanding of processes, activities, and releases. Go to [Key concepts](/release-orchestration/new-to-release-orchestration/key-concepts.md) to review them.
## Permissions for releases, activities, and processes
In **Access Control**, a role has a **Release Management** section with one row for each of the following resources: **Releases**, **Activities**, and **Processes**. Each row has the following permissions: **Create**, **View**, **Edit**, **Delete**, and **Execute**.
Before process and activity permissions, this section included permissions for **Releases** only, which also applied to processes and activities. With the new permissions, you can grant access to each resource independently.
The following rules apply to the permissions:
* Anyone with **View** on **Releases** automatically gets **View** on **Activities** and **Processes**. You must grant every other permission explicitly.
* Other areas of Release Management, such as reports and webhooks, continue to use the **Releases** permissions.
* Enabling the feature does not give new access to roles that never had **Releases** permissions.
### Required permissions by action
The permissions you need depend on what you start. Use the following table to decide which permissions to grant.
| Action | Permissions required |
| ---------------------- | ----------------------------------------------------------------- |
| Start a release | **Execute** on **Releases**, **Processes**, and **Activities** |
| Run a process directly | **Execute** on **Processes** and **Activities** |
| Author a process | **Create**, **Edit**, and **Delete** on **Processes**, as needed |
| Author an activity | **Create**, **Edit**, and **Delete** on **Activities**, as needed |
### Activity execute permission validation
Harness checks the **Execute** permission on **Activities** for the person who started the release (the initiator), not for the person who performs a later action on the release. This behavior has the following effects:
* An operator who retries a failed step needs **Execute** on **Releases** and **Processes**, but the initiator must still have **Execute** on **Activities**.
* A subprocess or a nested process run uses the initiator of the parent release.
## Migrate existing custom roles
If you have custom roles with **Releases** permissions, Harness can automatically add the corresponding **Processes** and **Activities** permissions to those roles, so they continue to work with the new permissions.
The migration behaves as follows:
* It adds a matching permission to a custom role only when the role already has the corresponding **Releases** permission.
* It does not change Harness-managed roles.
* It runs once for your account, in the background, after Harness rolls out the service version that includes this feature. You do not need to start it.
Perform the following steps to verify that your custom roles were migrated:
{% stepper %}
{% step %}
### Open the roles
Go to **Access Control** -> **Roles** and open a custom role that has **Releases** permissions.
{% endstep %}
{% step %}
### Verify the permissions
Confirm that the **Release Management** section shows the **Processes** and **Activities** permissions that match the **Releases** permissions of the role.
{% endstep %}
{% endstepper %}
## Pipeline identity
When a release runs a pipeline activity, Harness must decide which identity starts the pipeline. A project default setting controls this choice.
To find the setting, go to **Project Settings** -> **Default Settings** and open the **Release Management** group. The setting is **Use Service Principal for Pipeline Authentication**. You can set it at the account, organization, or project scope. A change is not applied immediately. Wait about 2 minutes after you save it before you start a release that depends on it.
### Identity modes
The following modes control which identity runs a pipeline activity.
| Mode | Setting | Behavior |
| ---------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| User and service | **Use Service Principal for Pipeline Authentication** is off | The Release Management service starts the pipeline on behalf of the initiator. The initiator must have **Execute** permission on the pipeline. |
| Service only | **Use Service Principal for Pipeline Authentication** is on | Only the Release Management service identity is used. Harness does not check **Execute** permission on the pipeline. |
In the legacy behavior, the service runs the pipeline without forwarding a user identity, and Harness still checks the pipeline **Execute** permission.
If Harness cannot read the setting, it keeps the safer behavior and still checks the pipeline **Execute** permission.
{% hint style="info" %}
**Why use the service only**
Without the setting, a person who starts a release but lacks **Execute** permission on the pipeline sees the pipeline fail to execute because it runs with the initiator's permissions. With **Use Service Principal for Pipeline Authentication** on, having permissions on the release, process, and activity is enough to run the pipeline.
{% endhint %}
### Permissions by combination
Use the following table to see what the initiator needs for each combination of settings.
| Process and activity permissions | Pipeline identity | What the initiator needs |
| -------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| On | User and service | **Execute** on **Activities** and **Execute** on the pipeline |
| On | Service only | **Execute** on **Activities** only |
| Off | Service only | **Execute** on **Activities** is not enforced as a separate permission, because the **Releases** permissions apply. Harness does not check **Execute** on the pipeline. Use this combination only when that is acceptable for your account. |
## Example scenarios
The following scenarios show how the permissions apply to common roles.
* **Process author only**: Grant **Create**, **View**, **Edit**, and **Delete** on **Processes**. They can build and change processes but cannot run them, because they lack **Execute**.
* **Activity author only**: Grant **Create**, **View**, **Edit**, and **Delete** on **Activities**. They can maintain activities in the Activity Store but cannot run releases.
* **Operator who retries**: Grant **Execute** on **Releases** and **Processes**. The operator can retry steps, but the release runs only if the initiator has **Execute** on **Activities**.
* **Pipelines show the human**: Keep **Use Service Principal for Pipeline Authentication** off. The pipeline execution record shows the initiator, and the initiator needs pipeline **Execute** permission.
* **Pipelines run as the service**: Turn on **Use Service Principal for Pipeline Authentication**. The pipeline runs as the Release Management service, and the initiator does not need pipeline **Execute** permission.
* **Subprocesses**: A subprocess uses the initiator of the parent release, so you do not grant separate permissions for nested runs.
## Troubleshooting
A release cannot start
Confirm that the person who starts the release has **Execute** on **Releases**, **Processes**, and **Activities**. Anyone with **View** on **Releases** gets **View** on processes and activities automatically, but **Execute** is never granted automatically.
A pipeline execution fails when a release runs it
If **Use Service Principal for Pipeline Authentication** is off, the pipeline runs on behalf of the release initiator, so the initiator needs **Execute** permission on the pipeline. Either grant that permission, or turn the setting on so that the Release Management service runs the pipeline.
A retry fails even though the operator has release and process execute permissions
Harness checks **Execute** on **Activities** for the initiator of the release, not the operator. Grant **Execute** on **Activities** to the initiator.
A custom role does not show the Processes and Activities permissions
The migration adds a permission only to custom roles that already have the matching **Releases** permission, and it does not change Harness-managed roles. The migration runs once for your account, in the background, after the service rollout. If the role still does not show the permissions after the rollout, contact [Harness Support](mailto:support@harness.io).
A change to the pipeline identity setting has no effect
A change to **Use Service Principal for Pipeline Authentication** is not applied immediately. Wait about 2 minutes after you save it, and then start a new release. Check that you set the value at the scope where the release runs, because the setting can be configured at the account, organization, or project scope.
***
## Next steps
* [Executing a release](/release-orchestration/use-release-orchestration/release-orchestration-execution/executing-a-release.md): Start a release and follow its execution.
* [Governance of a release - OPA policy](/release-orchestration/use-release-orchestration/release-orchestration-execution/opa-governance-for-releases.md): Enforce governance rules on releases and processes with OPA policies.
* [Key concepts](/release-orchestration/new-to-release-orchestration/key-concepts.md): Review releases, processes, and activities.
{% @harness-feedback/feedback %}