Environment scopes — repository, environment, and organisation granularity

A CI secret has a scope, and the scope determines which jobs can read it. The scoping model is the structural control that turns a CI secret from a shared credential into a least-privilege credential. A production cloud credential in the repository scope is a credential every job in the repository can read, including the PR-triggered build from a fork. The same credential in an environment scope with a required-reviewer rule is a credential only the protected job can read, only after a human has approved the deployment, and only on a branch that the environment accepts.

The three scopes

CI forges partition secrets into three scopes. The scope is set when the secret is created; the scope determines which jobs can read the value.

flowchart TB
    subgraph ORG["Organisation scope"]
        OA["Org secret A"]
        OB["Org secret B"]
    end
    subgraph REPO["Repository scope"]
        RA["Repo secret A"]
        RB["Repo secret B"]
    end
    subgraph ENV["Environment scope"]
        EA["Env: production secret"]
        EB["Env: staging secret"]
        EC["Env: dev secret"]
    end
    ORG -->|opt-in per repo| REPO
    REPO -->|opt-in per workflow| JOB1["Any job\nin the repo"]
    ENV -->|opt-in per workflow and protection rules| JOB2["Protected job\non accepted branch\nafter approval"]

The three scopes, with their properties:

• Repository scope. The secret is available to every workflow in the repository. The repository scope is the default; secrets created through the repository’s settings page are repository secrets. A repository secret is a secret every PR-triggered build can read, including builds from forks (subject to the forge’s fork-PR secret policy).
• Environment scope. The secret is available only to jobs that target a named environment. The environment has protection rules: required reviewers, wait timers, branch restrictions. An environment secret is a secret only the gated job can read, only on the gated branch, only after the gate has cleared.
• Organisation scope. The secret is available to every repository in the organisation that opts in. The organisation scope is the broadest; the secret is shared across the team’s repositories. An organisation secret is the right scope for a credential every repo legitimately needs (a shared artifact registry token, a shared notification webhook), not the right scope for a credential one repo needs.

Environment protection rules

An environment is more than a scope; an environment is a gated surface. The protection rules the forge supports turn an environment into a deploy gate:

• Required reviewers. The deploy job pauses at the environment; the job does not run until a designated reviewer has approved the deployment. The reviewer’s approval is an out-of-band signal: the reviewer’s account is not the runner’s account; the reviewer’s decision is logged in the audit trail.
• Wait timer. The deploy job cannot run until a configured delay has elapsed. The delay is a cool-off window: an attacker who triggers a deploy has minutes to be detected before the deploy runs.
• Branch restriction. The environment accepts jobs only from a configured branch or branch pattern. A production environment that accepts only main is an environment a fork PR cannot deploy to.
• Deployment branches (GitLab). The GitLab equivalent of branch restriction, with the same effect: the job runs only on the configured branch.

flowchart LR
    PR["Pull request\nto main"] --> CI["CI build\non PR head"]
    CI -->|tests pass| MERGE["Merge to main"]
    MERGE --> DEPLOY["Deploy workflow\ntargets env: production"]
    DEPLOY --> WAIT{"Wait timer\nelapsed?"}
    WAIT -->|no| H["Hold"]
    WAIT -->|yes| APPROVE{"Required reviewer\napproved?"}
    APPROVE -->|no| H
    APPROVE -->|yes| BRANCH{"Branch"}
    BRANCH -->|no| H
    BRANCH -->|yes| RUN["Job runs\nreads env secret"]

The three rules compose. A deploy job that targets the production environment cannot run until the wait timer has elapsed, a reviewer has approved, and the branch is accepted. The deploy job’s blast radius is the production environment’s blast radius, gated by three controls.

Scoping and least privilege

The principle of least privilege applies to secrets the same way it applies to IAM policies: the credential should hold the permissions the workload needs, no more. In the CI secret model, “permissions” decomposes into two dimensions:

• What the credential grants. A scoped IAM role, a per-environment service account, a per-deploy Vault token. The credential’s authority is bounded at the source.
• Who can read the credential. The forge’s scope model determines which jobs can read the value. The scope should be the narrowest scope the workload needs.

A production AWS access key in the repository scope violates both dimensions: the key may grant broad permissions (the team did not scope the IAM role), and the key is readable by every job in the repo (the repository scope grants access to every job). The same key in an environment scope, paired with an OIDC role that grants only s3:PutObject on the deploy bucket, satisfies both dimensions.

Multi-repository scoping

An organisation with multiple repositories faces a scoping choice: which secrets are repository-scoped, which are environment-scoped, and which are organisation-scoped. The default that minimises blast radius:

• Repository scope. Secrets that are unique to one repository: a per-repo deploy key, a per-repo integration token, a per-repo webhook. The secret is not shared because the credential is not shared.
• Environment scope. Secrets that are unique to one environment: a production cloud credential, a staging database password. The secret is environment-specific because the credential is environment-specific.
• Organisation scope. Secrets that are shared across the team’s repositories: a shared artifact registry token, a shared notification webhook, a shared code- scanning service. The secret is shared because the credential is shared.

A organisation that puts a production credential in the organisation scope has built an organisation-wide production credential. The blast radius of the organisation scope is the blast radius of the organisation.

Production discipline

1. Production secrets in production environments. No production credential in the repository or organisation scope. The production credential lives in the production environment, gated by the protection rules.
2. Required reviewers for deploy environments. The production environment requires a reviewer who is not the deploy author. The reviewer’s approval is logged in the audit trail.
3. Branch restrictions on deploy environments. The production environment accepts only main (or the team’s release branch). A fork PR cannot deploy to production.
4. Wait timer for production deploys. A 5-minute wait timer on the production environment is a cool-off window for an attacker who triggered an unauthorised deploy.
5. Audit secret scopes quarterly. Review the scope of every secret; flag any production-scoped credential whose scope is broader than the workload.

Cross-course references

• Git, CI/CD & GitOps — Part XXXII-03 (Required approvals and status checks) covers the PR-side approval gating that complements environment gating.
• Git, CI/CD & GitOps — Part XLI-06 (Persistence and lateral movement) covers the post-leak blast radius when a broad scope meets a malicious step.
• AWS for Production Sysadmins — Part XXXI (IAM) covers the role-scoped credentials that pair with the environment-scoped secrets.

Quiz