Secrets, Environments, Variables, Redaction, and Credential Hygiene: Configuration, Design Patterns, and Trade-Offs

1. Minimize both secret lifetime and secret audience

Least privilege applies to stored credentials too. A credential should exist only if another identity mechanism cannot satisfy the use case, should be scoped to the smallest resource set, should be available only to jobs that need it, and should live only as long as required.

A useful design question is not “where can I store this token?” but “why does this job need a long-lived token at all?”

2. Identity/configuration decision table

3. Scope follows ownership, not YAML reuse

A repository secret is a good default when one repository owns the integration. An organization secret is appropriate only when one credential legitimately spans multiple approved repositories and has an access policy. An environment secret is appropriate when the credential belongs to a deployment stage and should not exist in ordinary build/test jobs.

4. Build jobs and credential-bearing jobs should be different security zones

permissions: {}

jobs:
  build_and_test:
    runs-on: ubuntu-24.04
    steps:
      - run: echo 'Build/test with no deployment credential.'

  deploy_gate:
    needs: build_and_test
    runs-on: ubuntu-24.04
    environment: staging
    env:
      DEPLOY_CREDENTIAL: ${{ secrets.STAGING_DEPLOY_CREDENTIAL }}
    steps:
      - name: Use credential only after environment eligibility
        run: |
          set -euo pipefail
          test -n "$DEPLOY_CREDENTIAL"
          echo 'credential_available=true; external deployment omitted in this course chapter'

The example deliberately does not deploy anything. Its purpose is to show that credential availability begins at the side-effect boundary, not at workflow start. In production, deploy the exact verified artifact from CI rather than rebuilding inside the privileged job.

5. Long-lived cloud secret versus OIDC

OIDC does not mean “no security configuration.” The provider trust policy becomes the authorization layer and must constrain repository/workflow/ref/environment/audience claims. Chapter 20 owns the implementation details.

6. Reusable workflows are credential contracts

Secrets are not automatically passed to reusable workflows. A caller can pass explicitly named secrets or, where supported, use secrets: inherit to make all secrets available to the directly called workflow. The latter is convenient but broadens the callee's credential audience.

jobs:
  call_release_workflow:
    uses: ./.github/workflows/release.yml
    secrets:
      registry_token: ${{ secrets.LAB_REGISTRY_TOKEN }}

Prefer named contracts for production boundaries: the callee documents exactly which credential it requires. Treat secrets: inherit as an explicit trust decision, not a default shortcut. Nested workflows do not magically receive every upstream secret; secrets must cross each call boundary deliberately.

7. Plan and repository visibility are part of the design

Current GitHub environments/environment secrets are available to public repositories on current plans. Environment secrets for private/internal repositories require GitHub Pro, Team, or Enterprise, and some protection features have additional visibility/plan restrictions. Organization-level secrets/variables are not available to private repositories on GitHub Free.

A course design must therefore provide a public disposable or faithful simulation path. A production design must record the repository visibility and plan assumptions rather than silently relying on a UI that another team cannot use.

8. Rotation and revocation need ownership metadata

For every long-lived secret, maintain an owner, source system, scope, purpose, rotation cadence, emergency revocation procedure, and list of consuming workflows. Use separate credentials for unrelated systems so one rotation does not become an organization-wide outage.

Do not expose secret-derived hashes in logs just to “prove” rotation. Prefer provider audit records, successful narrow authentication, version metadata that is explicitly non-secret, and a fresh run whose start falls after the rotation boundary.

9. Worked scenario: choose the smallest credential architecture

A repository builds a container, publishes it to a registry, then deploys to cloud infrastructure. A weak design gives one long-lived cloud administrator key to every job. A stronger design separates:

1. build/test job: no deployment credential;
2. registry publish job: registry-scoped identity only;
3. deployment job: protected environment plus OIDC to the cloud provider;
4. GitHub issue/status mutation: job-local GITHUB_TOKEN permission.

Each side effect receives its own identity and evidence. Compromise of one job does not automatically grant every other authority.

Knowledge check

Official references and version notes

• Secrets concept — current model for repository, organization, and environment Actions secrets and how workflows receive them.
• Secrets reference — current naming, precedence, size/count limits, queue/start read timing, and automatic redaction behavior.
• Using secrets in GitHub Actions — current workflow injection patterns, missing-secret behavior, fork/Dependabot restrictions, masking guidance, CLI setup, and OIDC recommendation.
• Variables concept — current distinction between non-sensitive configuration variables and secrets.
• Variables reference — current vars scope, precedence, limits, and environment-variable semantics.
• Deployments and environments — current environment secret availability, protection-rule timing, plan/visibility boundaries, and self-hosted-runner warning.
• Events that trigger workflows — current fork pull-request secret restrictions and read-only token behavior.
• Dependabot on GitHub Actions — current Dependabot-specific token and secret restrictions.
• Workflow syntax — current secrets, environment, reusable-workflow secret passing, and conditional semantics.
• Workflow commands — current ::add-mask:: behavior and environment-file commands.
• Secure use reference — current guidance for rotating/removing secrets, approval gates, untrusted input, and credential hygiene.
• OpenID Connect — current model for exchanging GitHub OIDC identity for short-lived provider credentials instead of storing long-lived cloud secrets.
• Reuse workflows — current explicit secret passing, secrets: inherit, and directly-called workflow boundaries.