When an automation tool operates in a production environment, the question of granting permissions is critical. A request like “fix this deployment” doesn't specify in advance what actions the tool will take or what access it will need. If we grant it overly broad permissions, the slightest error can have unintended impacts on unrelated resources. Conversely, requiring approval for every individual step leads to user fatigue and routine clicking without deeper thought.
A modern approach involves the automation tool first investigating the problem, then proposing a concrete plan of actions that clearly shows what it intends to do and what access it will need. Approving such a plan grants the additional permissions necessary for its execution. This allows the user to thoroughly review the proposed fix before permitting any changes.
The proposed plan is crucial because it precisely determines the required permissions. In the event of a production deployment failure, the tool can first examine recent deployments and build logs. For this phase, read-only access is fully sufficient, enabling automated investigation. If this leads to a proposal for a new deployment, the tool requests additional access within the plan, which the user can review and approve with a single decision. Access is defined using “scopes,” which are named capabilities recognized by the platform's authorization system. Any plan requiring access beyond basic read-only access awaits approval as a whole, including any read-only tasks it contains. For longer investigations, the tool can create a read-only plan so the user can monitor its tasks and progress.
A plan connects user intent with what the automation tool is allowed to do. It includes: Intent: The desired outcome from the user. Work: The tasks proposed by the tool to achieve the intent. Access: The permission scopes these tasks require. Enforcement: The credentials and API checks that enforce access restrictions. Each stored plan records its tasks and progress, with the required scopes attached to individual tasks. Task descriptions explain why access is needed, and scopes are combined across the entire plan. Basic read-only access currently includes every registered scope starting with the “read:” prefix. Plans require approval if they request access beyond this baseline or include supported external actions, such as opening a pull request on GitHub. Read-only operations can still expose sensitive information, so automatic approval does not mean the work is without risk.
An important principle is that the automation tool can only use permissions that the user already possesses. The tool functions as a service application that the user authorizes to act on their behalf within the team. This authorization is limited by the user's existing permissions, so approving a plan cannot grant access that the user himself does not have. The authorization service then exchanges this authorization for short-lived tokens with precisely defined scopes that specify permitted capabilities, such as reading deployments or changing project settings. Platform APIs check the token with each request to enforce these restrictions. A user can authorize the tool for a team with dozens of projects. A new deployment plan requires write access to deployments. Modifying environment variables, changing domains, and managing team membership each require their own permissions. Write access to deployments is broader than one specific new deployment. Naming “deployment X” in the plan does not, by itself, restrict the token solely to that deployment. The runtime environment, the software that coordinates the tool's execution, verifies that the plan is active before selecting its approved credentials. Platform APIs check each request against the permissions of these credentials.
Plan approval precisely determines what permissions the automation tool can utilize. When a user approves a plan that needs additional access to platform features, the requested scopes are re-checked, and a token is prepared containing basic read permissions plus the approved permissions. The runtime environment verifies that the plan is active before selecting the approved credentials. These credentials remain subject to their scopes, team, user permissions, and validity period. Instructions governing the tool's behavior guide it on when to propose a plan and request approval. If it attempts an operation outside the token's permissions, platform APIs will reject the request, even if the tool considered the action necessary to complete the task. A single plan can encompass both platform changes and a GitHub pull request. The user reviews both actions within one plan, with each provider using separate permissions and credentials. GitHub pull request access is tied to the owner and repository, so approval for opening a request in `acme/storefront` applies to that repository, even if the user also has access to `acme/payments`. Opening a request there would require separate approval.
To ensure consistency and prevent discrepancies, it is crucial for plans and tokens to utilize the same permission definitions. In the past, we maintained a separate list of permissions for the tool, which could diverge from the authorization service that issues tokens. We transitioned to the same scope definitions so these inconsistencies could be caught during planning. During session setup, the tool loads these definitions from the platform's scope registry into an internal catalog. Loading the registry requires authorization for the team, while the scope definitions themselves are shared across teams. The catalog then provides definitions used in three phases: Plan Validation: Requested scopes are normalized, and unknown or malformed names are rejected, even before the plan is saved or presented for approval. Approval: Requested scopes determine whether the plan fits within basic read permissions or needs additional access. Token Preparation: Valid scopes define credentials for the approved work. For example, a task to update firewall rules might request an outdated scope. The system will reject the proposed plan and return valid scopes so the tool can make corrections before requesting approval. This catches inconsistencies during planning and requires explicit correction instead of reverting to broader access. Loading the registry adds latency and service dependency, so the tool caches the catalog and uses this copy to validate saved plans when loading them. These checks reflect the cached definitions until the catalog is refreshed with changes from the registry.
An active and approved plan is essential for resuming work. It can happen that the tool receives approval after the original request has ended, or it loses connection before executing an approved deployment. A stored plan contains its status, who approved it and when, along with its tasks and required permissions. This record links the proposed work to the access authorized by the user, allowing approval to be verified when work resumes. Before resuming, the runtime environment reloads the plan and checks if it is active before selecting credentials with its approved permissions. A stopped plan will not pass this check, even if the token is still valid. If an investigation reveals that the existing plan needs to be replaced, the tool can propose another one. A replacement plan requiring elevated permissions needs its own approval, thereby giving the user the opportunity to review the revised work and permissions together.
As automation tools expand into other areas of the platform, we must adjust access rules for actions involving multiple resources or having different consequences. For instance, connecting a domain may require permissions for both the domain and the project, while preparing a firewall rule and publishing it need different levels of access. Permission scopes must accurately capture these distinctions, while the access request in each plan must remain comprehensible. Precisely assigning these scopes to the proposed solution requires meticulousness throughout the planning process: Scope Selection: The tool selects scopes with incomplete information, so it might request too little access (leaving a task blocked) or too much (granting more authority than the work needs). Task-level guidance helps with selection, while validation catches invalid scope names. Even a valid scope can grant broader access than necessary. Work Description: “Redeploy the last successful build” gives the user a concrete action to consider, whereas scope names alone force them to infer consequences. The plan must explain the intended change and clearly indicate what restrictions the token actually enforces. Understanding Rejections: A rejected operation can indicate a missing scope, an incorrect resource, or an operation that should remain blocked. The tool must distinguish these cases before requesting additional permissions.
Got an idea for a website or app?
Let's talk it through — non-binding, with no pressure, and a concrete next step.
Even with correct permissions, a new deployment requires an assessment of whether the selected commit is safe to implement. This depends on the application, the nature of the failure, and the proposed fix. The user needs enough information to assess the choice, and the tool must execute the action correctly. Read-only investigations also require controls over the information retrieved, including sensitive project configuration and operational details. Basic read-only access was chosen so the tool could perform investigations before requesting approval, and this choice needs continuous review as scopes and the information they reveal change. Other systems may need narrower basic permissions. Separate controls must govern how retrieved information is handled and where it can go. The tool might make a poor decision or encounter malicious instructions in content it reads, such as build logs. Limited credentials restrict operations it can perform in both cases, but even permitted operations can cause harm. Therefore, plans work in conjunction with sandbox isolation, network policies, secret handling, rate limits, audit logs, and service authorization. Work on security boundaries in agent architectures clarifies the separation between the agent, its credentials, and the code it executes.
This approach ensures that authority remains tightly coupled to the specific work that requires it. The runtime environment selects approved credentials for the active plan, and its scopes precisely define what operations the automation tool can perform. Thanks to prior investigation, the user has the opportunity to assess the proposed solution and the associated required access in one comprehensive step.