Add documentation for assigning roles to stack tokens (#15696)

* Add documentation for assigning roles to stack tokens

* Update content/docs/pulumi-cloud/deployments/permissions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update content/docs/pulumi-cloud/deployments/permissions.md

Co-authored-by: Josh Kodroff <jkodroff@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Josh Kodroff <jkodroff@users.noreply.github.com>

Author: 3 people

content/docs/pulumi-cloud/deployments/permissions.md

@@ -33,7 +33,9 @@ The permission model has the following practical implications:
 
 ## Granting Additional Permissions
 
-If you want to change the permissions that are granted to a deployment, you can do so by setting the `PULUMI_ACCESS_TOKEN` environment variable to a token with the desired permissions in the stack's deployment settings.
+The recommended approach for granting additional permissions to deployments is through role assignment. To assign a role to a deployment, navigate to your stack's deployment settings in the Pulumi Console under `Settings > Deploy`. In the Role assignment section, use the dropdown menu to select from the available organization roles. Once a role is assigned, the deployment's stack token will inherit the permissions associated with that role, enabling access to stack references, environments, and organization resources as needed. Organization roles are managed through the [Roles section](../../access-management/rbac/roles/).
+
+Alternatively, you can set the `PULUMI_ACCESS_TOKEN` environment variable to a token with the desired permissions in the stack's deployment settings.
 
 This token can be an individual, team, or organization token, and it will grant the deployment the permissions that are associated with the token. If this environment variable is set, it will be used regardless of how the deployment was created (REST API, `git push`, etc.).
 

content/docs/pulumi-cloud/deployments/using/settings.md

@@ -53,6 +53,20 @@ When using Pulumi Deployments, you have options for where your deployments run:
 
 For more information on customer-managed agents, see the [Customer Managed Agents documentation](../../customer-managed-agents).
 
+### Role assignment
+
+When configuring deployment settings, you can assign organization roles to the stack token used for deployments. This setting appears as a dropdown menu under "Role assignment" that displays available organization roles.
+
+If no role is selected, the deployment will only have access to the specific stack being deployed. However, this limited access can cause failures when the deployment needs to:
+
+- Access stack references from other stacks
+- Access environments
+- Manage organization resources such as teams, members, or OIDC issuers
+
+By selecting an appropriate role, you provide the deployment with the necessary permissions to access these additional resources. For fine-grained access control, you can create custom roles with specific permissions tailored to what the deployment needs to accomplish.
+
+Organization roles are managed through the Roles section. For more information on creating and managing roles, see the [Roles documentation](../../../access-management/rbac/roles/).
+
 ## Pre-Run Commands
 
 Pre-run commands allow you to execute arbitrary shell commands before the deployment process starts. This is useful for environment setup, authentication with private package repositories, or other preparatory work. Note that each line of your pre-run command runs in a separate shell.