Reorganize "Using Deployments"

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

@@ -30,25 +30,6 @@ Deployments will remain in the queue for a maximum of 7 days. If a deployment is
 
 It is possible to pause deployments at the stack or organization level. Deployments that are already running are allowed to complete and are not paused. New deployments are queued, and will run when the stack or organization’s deployments are resumed.
 
-## Dependency caching
-
-When using Pulumi-managed deployment agents, you have the option to speed up deployments using *dependency caching*.
-
-The caching method is simple: during the first deployment, the deployment agent will automatically detect downloaded dependencies using lock files, zip them up and store the archive in blob storage. During all subsequent deployments, agents will pull such an archive down and unpack it, saving time it would normally take to download those dependencies. When your dependencies change, deployment agents will automatically invalidate the old cache and create a new one.
-
-Caches are shared on the project level, so all stacks within a project can share the same cache. However, caches are fully isolated and never shared between customers.
-
-Dependency caching is supported for the following runtimes:
-
-- `.NET` - no special configuration required
-- `Python` - ensure that you have `requirements.txt` in the root of your source code.
-- `Go` - ensure that you have `go.mod` and `go.sum` in the root of your source code.
-- `NodeJS` - ensure that you have `packageManager` field specified in `package.json`. For now, only `npm` and `yarn` are supported.
-  - For `npm`, ensure that you have `package-lock.json` in the root of your source code.
-  - For `yarn`, ensure that you have `yarn.lock` in the root of your source code.
-
-To confirm dependency caching is working and/or to troubleshoot, check out logs of your deployments, specifically the `Restore Cache` and `Save Cache` steps.
-
 ## Common recipes
 
 See [Using Deployments](/docs/pulumi-cloud/deployments/reference/) for common recipes and best practices.

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

@@ -0,0 +1,71 @@
+---
+title_tag: "Deployment Permissions | Pulumi Deployments"
+meta_desc: Learn how to configure and manage permissions for Pulumi Deployments
+title: "Deployment Permissions"
+h1: "Deployment Permissions"
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  cloud:
+    parent: pulumi-cloud-deployments
+    weight: 8
+---
+
+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](https://www.pulumi.com/docs/concepts/stack/#stackreferences), 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](https://www.pulumi.com/docs/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](/docs/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](/docs/esc/).
+
+You can use ESC with pre-run commands in Deployments by prefixing each command with `pulumi env run`. For example:
+
+```bash
+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.