A deployment review must connect the GitHub job context to AWS trust conditions and the resource permissions of the resulting session. This guide develops a review record and negative test set for repository, environment and reusable workflow boundaries without treating short credential lifetime as sufficient authorization.
At a glance
Key findings
- An environment name in an OIDC subject is not evidence that a deployment came from an approved branch. Environment policy supplies that separate restriction. [1][3]
- The AWS trust decision and the permissions of the resulting role session answer different questions. Review both. [4]
- Use explicit rejection cases for the wrong repository, audience and job context before accepting a trust-policy change.
Define the deployment authority
A deployment role is an entry point into a production system. Its review should begin with a sentence precise enough to reject a plausible alternative: this repository, running this deployment job, under these approval conditions, may update these resources. A statement such as “GitHub may deploy” leaves the essential decisions unresolved. The token exchange can work correctly while the intended boundary remains much wider than the team assumes.
GitHub's AWS integration uses an OpenID Connect token in place of a stored cloud credential. Its guidance calls for checking the audience and subject in the AWS role trust policy. Requesting id-token: write permits the job to obtain the OIDC token; it does not by itself grant permission to change an AWS resource. [1]
Keep a compact authority record beside the workflow: repository owner, workflow file, target environment, permitted source refs, AWS role ARN, resource scope and policy owner. Record who may change each item. This is a review artifact, not a claim that the listed controls have been tested. A reviewer should be able to follow the intended deployment from source approval to the final resource action without interpreting an organization-wide diagram.
Read the subject that the job actually presents
The default subject depends on the job context. A branch job can use repo:ORG/REPO:ref:refs/heads/BRANCH, while a job referencing an environment uses repo:ORG/REPO:environment:ENVIRONMENT. GitHub also documents other subject forms and customization options. An environment subject therefore cannot be read as if it contained the branch claim shown in the first example. [2]
During an authorized rehearsal, inspect the necessary claims through a safe diagnostic process and retain only a redacted claim summary. Do not copy a usable bearer token into a ticket or public build log. Compare the exact subject and audience with the actual conditions on the target role, including case, punctuation and encoded characters where applicable.
Treat a change from a branch job to an environment job as an authorization change. A successful deployment after that change is useful functional evidence, but it does not explain which unintended jobs could also qualify. Ask which previous constraint moved, where it is enforced now and who can alter its replacement.
The controls that decide whether a deployment job gets a role
Review the job context, environment restrictions, role trust and resource permissions as four distinct decisions.
Source. Primary documentation [1] [2] [3] [4] [5]. Accessed August 28, 2026.
Method. Original authorization schematic synthesized from GitHub and AWS documentation. Its gates and table show review decisions and hypothetical contexts, not observed token traffic or measured success rates.
Accessible table and figure data
| Hypothetical context | Trust condition result | Additional evidence |
|---|---|---|
| Approved repository and exact permitted context | Expected match | Environment review and role permissions still required |
| Wrong audience | Expected rejection | Compare configured aud with redacted claim |
| Different repository | Expected rejection with exact sub | No organization-wide wildcard assumed |
| Environment job from an unapproved ref | Depends on environment branch policy | Do not infer branch approval from environment sub |
| Reusable workflow changed | Depends on chosen subject template | Record caller and reusable-workflow identity |
| Hypothetical context | Trust condition result | Additional evidence |
|---|---|---|
| Approved repository and exact permitted context | Expected match | Environment review and role permissions still required |
| Wrong audience | Expected rejection | Compare configured aud with redacted claim |
| Different repository | Expected rejection with exact sub | No organization-wide wildcard assumed |
| Environment job from an unapproved ref | Depends on environment branch policy | Do not infer branch approval from environment sub |
| Reusable workflow changed | Depends on chosen subject template | Record caller and reusable-workflow identity |
Review environment policy beside the role
GitHub environments can apply deployment branch or tag restrictions and protection rules such as required reviewers. The available protections depend on the repository and plan. Reviewer settings also include choices affecting self-review and administrator bypass. Naming an environment in a workflow does not establish that these protections have been configured as the reviewer expects. [3]
The environment record belongs in the same review as the trust policy. Document the allowed refs, approval rule, bypass behavior and people who can edit the environment. If the desired control is “a reviewed release from the protected branch,” every part of that statement needs an enforcement point. An environment label alone establishes none of the organizational approval evidence.
A useful negative case is a deployment attempt using the same environment from a ref that should be excluded. Another is an attempt by the person who initiated the deployment when independent approval is required. These are proposed acceptance checks. Run them in an isolated deployment target with permission from its owner, and preserve the result without exposing tokens.
Write the negative cases before rollout
IAM requires a GitHub OIDC trust policy to contain a subject condition that is not null or solely a wildcard. This safeguard rejects some excessively broad policies, but a syntactically accepted subject pattern can still permit more repositories or contexts than intended. The role's trust policy determines assumption; subsequent resource access also depends on applicable AWS permissions. [4]
Build a test set from the authority record. Include the approved job, a different repository, an incorrect audience, a disallowed ref using the deployment environment and a caller that uses an unapproved reusable workflow. For each case, name the control expected to reject it. The accessible table distinguishes cases that should fail in trust evaluation from those dependent on environment settings.
Separate session issuance from deployment authorization in the evidence. A job obtaining a role session does not establish that its resource permissions are appropriate. Conversely, a denied resource action does not show that the trust policy is narrow. Use a harmless, explicitly approved target action for the second check and record both outcomes independently.
Keep the evidence attached to change review
The lasting output should be a versioned decision record, not a screenshot of a successful run. Keep the workflow revision, redacted claim expectations, environment configuration, role trust revision, resource policy scope and acceptance results together. Identify any case that remains untested and the person responsible for resolving it.
Reopen the review when a repository moves, an environment is renamed, a subject template changes or the shared workflow's authority expands. These events can alter an authorization assumption without changing the application code being deployed. A short review checklist tied to those changes is more useful than a recurring reminder that asks only whether credentials are temporary.
Keep the approved subject expectations readable without requiring a future reviewer to decode a token from an old run. Record where the live trust conditions and environment rules are maintained, and assign an owner to reconcile them after a workflow change. If a rejected case later becomes a legitimate deployment requirement, update the authority record and test set together rather than quietly broadening the trust pattern.
Method and provenance
Documentation review and original operational analysis using the cited primary sources, checked on August 28, 2026. The editorial date places the article in the retrospective series; publication and source review occurred in August 2026.
No repository or AWS deployment was inspected. Repository-plan protections and customized subject support require verification for the intended deployment. Living documentation supports the publication-time review, not a claim about January feature availability. No empirical tests were performed for this article.
AI assistance. Researched, drafted and checked against cited sources with AI assistance. No independent human editorial review or original empirical testing is claimed.
Published under the Cloud Security Desk organizational byline. Read the series policy.
References
- Configuring OpenID Connect in Amazon Web Services GitHub. Accessed .
- OpenID Connect reference GitHub. Accessed .
- Deployments and environments GitHub. Accessed .
- Create a role for OpenID Connect federation Amazon Web Services. Accessed .
- Using OpenID Connect with reusable workflows GitHub. Accessed .