Deployment Permissions

This page explains how permissions work in Pulumi Deployments and how to configure them for your deployment needs.

Default Deployment Permissions

By default, the permissions that are granted to a deployment depend on how the deployment is being invoked:

• If the deployment is created via the REST API or by using the Actions buttons in the Pulumi Cloud console, it is granted the permissions of the user that has executed the action.
• If a deployment is created because of a git push or a pull request, it uses an ephemeral stack token that has admin permissions on only the stack itself, but nothing else.

Permissions Impact

The permission model has the following practical implications:

• If your organization has default stack permissions set to NONE, then any deployment created by a git push or a pull request will not be able to access any Stack References, and will fail if it tries to do so.

• If your organization has default environment permissions set to NONE, then any deployment created by a git push or a pull request will not be able to access any ESC Environments that are listed in the stack’s configuration file.

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.

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.).

Minimum Required Token Permissions

If using an individual or team token, the token must have at minimum:

• WRITE access to the stack that is being deployed
• READ access to any stacks from which Stack References are being used
• OPEN access to any ESC environment that is listed in the stack’s configuration file, including any environments that are imported transitively

Using ESC with Deployments

For enhanced security and simplified credential management, we recommend configuring your stack to use Pulumi ESC for cloud credentials and ensuring the Deployment has an appropriately scoped Pulumi token.

This approach offers several advantages:

• Dynamic, short-lived credentials instead of long-lived static credentials
• Fine-grained control over credential scope and permissions
• Centralized credential management
• Reduced risk of credential exposure
• Complete audit trail of credential usage

Configuring ESC for Deployments

1. Create an ESC environment with the appropriate cloud provider credentials
2. Reference this environment in your Pulumi stack configuration
3. Create a Pulumi access token with the appropriate permissions (as described above)
4. Add this token as the PULUMI_ACCESS_TOKEN environment variable in your deployment settings

For more information on setting up ESC environments, see the ESC documentation.

You can use ESC with pre-run commands in Deployments by prefixing each command with pulumi env run. For example:

pulumi env run my-aws-env -- aws s3 ls

This executes the aws s3 ls command with credentials from your my-aws-env ESC environment.