Skip to content

Enhancing custom permissions #2152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
trujillo-adam wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Enhancing custom permissions #2152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2c88b27
add org-level permissions
trujillo-adam Apr 3, 2026
f7e4ad6
added override permissions for ws and proj
trujillo-adam Apr 3, 2026
b5f3689
update desc of soft mandatory
trujillo-adam Apr 3, 2026
61363d9
Apply suggestions from code review
trujillo-adam Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions ...s-common/docs/cloud-docs/users-teams-organizations/permissions/organization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ The following table summarizes the available organization-level permission categ
| [Settings permissions](#settings-permissions) | Control access to governance and infrastructure tools. |
| [Private registry permissions](#private-registry-permissions) | Control access to the organization's private registry. |
| [Public registry permissions](#public-registry-permissions) | Control access to the public registry. |
| [Policy overrides](#policy-overrides) | Controls teams’ ability to override failed policy checks for policies with an enforcement level set to **Soft mandatory**. |

## Project permissions

Expand Down Expand Up @@ -214,7 +215,6 @@ The following permissions control access to governance and infrastructure tools.
| Permission name | Description |
|-----------------|-------------|
| [Manage policies](#manage-policies) | Create, edit, read, list and delete Sentinel policies |
| [Manage policy overrides](#manage-policy-overrides) | Override soft-mandatory policy checks |
| [Manage run tasks](#manage-run-tasks) | Create, edit, and delete run tasks |
| [Manage version control settings](#manage-version-control-settings) | Manage VCS providers and SSH keys |
| [Manage agent pools](#manage-agent-pools) | Create, edit, and delete agent pools |
Expand All @@ -229,12 +229,6 @@ This permission implicitly gives permission to read runs on all workspaces, whic

Allows members to create, edit, and delete run tasks on the organization.

### Manage policy overrides

Allows members to override soft-mandatory policy checks.

This permission implicitly gives permission to read runs on all workspaces, which is necessary to override policy checks.

### Manage VCS settings

Allows members to manage the set of [VCS providers](/terraform/cloud-docs/vcs) and [SSH keys](/terraform/cloud-docs/vcs#ssh-keys) available within the organization.
Expand Down Expand Up @@ -321,6 +315,34 @@ Allow members to publish and delete providers for the organization in the public

<!-- END: TFC:only name:public-registry -->

## Policy overrides

Policy override settings only apply to policies that have a **Soft mandatory** enforcement level. Refer to [Policy enforcement levels](/terraform/cloud-docs/policy-enforcement/manage-policy-sets#policy-enforcement-levels) for more information.

| Permission name | Description |
| --- | --- |
| [No policy overrides](#no-policy-overrides) | Teams can’t override failed **Soft mandatory** policy evaluations. |
| [Delegate policy overrides](#delegate-policy-overrides) | Allow project and workspace managers to grant override permissions for **Soft mandatory** policy evaluations. When this setting is enabled, the ability to override failed policy evaluations is disabled by default. Project and workspace managers must manually enable the **Allow policy overrides** setting in their projects and workspaces. |
| [Manage policy overrides](#manage-policy-overrides) | Team members can override failed **Soft mandatory** policy evaluations in all workspaces. |
Copy link
Copy Markdown

@segmentation-violation segmentation-violation Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it also worth making it explicit that Manage policy overrides gives read access to all workspaces in the organization, while Delegate policy overrides does not? The read all workspaces behavior of the existing setting has been a big pain point for customers, so I'm wondering if we can highlight how Delegate is better.

Copy link
Copy Markdown
Contributor Author

@trujillo-adam trujillo-adam Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added this to the more detailed description linked from this table.


### No policy overrides

Teams can’t override failed **Soft mandatory** policy evaluations.

### Delegate policy overrides

Allow project and workspace managers to grant override permissions for **Soft mandatory** policy evaluations. When this setting is enabled, overriding failed policy evaluations is disabled by default. Project and workspace managers must manually enable the **Allow policy overrides** setting in their projects and workspaces.

Copy link
Copy Markdown
Contributor

@mattschouten mattschouten Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These sections don't add much information beyond what's in the table already. What do you think about moving the "Refer to the projects and workspaces..." bit to the table, and removing these sections?

(I'm ok if not)

Copy link
Copy Markdown
Contributor Author

@trujillo-adam trujillo-adam Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm just following the template we set up. The separate headings also give us direct links to each setting.

Refer to the [projects](/terraform/cloud-docs/users-teams-organizations/permissions/project#policy-overrides) and [workspaces](/terraform/cloud-docs/users-teams-organizations/permissions/workspace#policy-overrides) team permission references for more information.

### Manage policy overrides

Team members can override failed **Soft mandatory** policy evaluations in all workspaces.

This setting also gives teams read access to all workspaces in the organization. To prevent read access, enable the [**Delegate policy overrides**](#delegate-policy-overrides) setting instead.

Refer to the [projects](/terraform/cloud-docs/users-teams-organizations/permissions/project#policy-overrides) and [workspaces](/terraform/cloud-docs/users-teams-organizations/permissions/workspace#policy-overrides) team permission references for more information.

## Organization owners

<!-- BEGIN: TFC:only name:hcp-eu -->
Expand Down
8 changes: 8 additions & 0 deletions ...m-docs-common/docs/cloud-docs/users-teams-organizations/permissions/project.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,14 @@ Allows users to see teams assigned to the project for visible teams.

Allows users to set or remove project permissions for visible teams. Project admins can not view or manage teams with **Visibility** set to **Secret** in their team settings unless they are also organization owners. Refer to [Team visiblity](/terraform/cloud-docs/users-teams-organizations/teams/manage#team-visibility) for more information.

## Policy overrides

You can configure the following policy override settings for the project.

### Allow policy overrides

Enable this setting to allow team members to override failed **Soft mandatory** policy evaluations in their project workspaces. Refer to [Policy overrides](/terraform/cloud-docs/users-teams-organizations/permissions/organization#policy-overrides) for more information.

## Run access

The following table summarizes the available run access permissions for workspaces within the project.
Expand Down
7 changes: 7 additions & 0 deletions ...docs-common/docs/cloud-docs/users-teams-organizations/permissions/workspace.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,13 @@ Allows users to view the values of Terraform variables and environment variables

Allows users to read and edit the values of variables in the workspace.

## Policy overrides

You can configure the following policy override settings for the workspace.

### Allow policy overrides

Enable this setting to allow team members to override failed **Soft mandatory** policy evaluations. The **Delegate policy override** setting must also be enabled for the team. Refer to [Policy overrides](/terraform/cloud-docs/users-teams-organizations/permissions/organization#policy-overrides) for more information.

## State access

Expand Down
2 changes: 1 addition & 1 deletion ...mmon/docs/cloud-docs/workspaces/policy-enforcement/manage-policy-sets/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ You can set an enforcement level for each policy that determines what happens wh
You can enable one of the following options to set the enforcement level when creating a Sentinel policy:

- **Advisory:** Failed policies never interrupt the run. They provide information about policy check failures in the UI.
- **Soft mandatory:** Failed policies stop the run, but any user with [Manage Policy Overrides permission](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-policy-overrides) can override these failures and allow the run to complete.
- **Soft mandatory:** Failed policies stop the run, but organization admins can configure the platform to allow team members to override failures so that runs can continue. Organization admins can either let all team members override **Soft mandatory** policy failures or delegate authority to project and workspace managers. Refer to [Policy overrides](/terraform/cloud-docs/users-teams-organizations/permissions/organization#policy-overrides) for more information.
- **Hard mandatory:** Failed policies stop the run. Unless the set containing the policy is configured to [allow overrides](#allow-policy-level-overrides), Terraform does not apply runs until a user fixes the issue that caused the failure.

#### Allow policy level overrides
Expand Down
Loading