Security & Permissions

GITHUB_TOKEN permissions, OIDC federation, branch protection, supply chain security, and hardening your CI/CD pipeline.

🧒 Simple Explanation (ELI5)

Imagine your GitHub Actions workflow is a person working inside a bank vault.

• GITHUB_TOKEN is your ID badge. Every employee gets one automatically when they walk in. But your badge only opens the doors you're authorised to access — not the entire building.
• The permissions block in your workflow is like choosing which floors your badge can open. By default it might open everything — but a smart security team limits it to only the floors you actually need. That's the principle of least privilege.
• OIDC federation is like a temporary visitor pass from a trusted partner. Instead of giving the visitor a permanent key (a stored secret), the partner company vouches for them and the bank issues a short-lived pass that expires in minutes. No keys to steal, no keys to lose.
• Branch protection is the security guard at the front door. Before anyone can enter (merge code), the guard checks their identity (reviews), makes sure they passed the background check (status checks), and verifies their signature (signed commits). No exceptions.

Put it all together: every worker has a limited badge, visitors get temporary passes, and guards check everyone at the door. That's how you secure a CI/CD pipeline.

🔑 GITHUB_TOKEN

Every workflow run automatically receives a GITHUB_TOKEN — a short-lived token scoped to the repository. Understanding and restricting its permissions is the foundation of workflow security.

How It Works

• Auto-generated at the start of every workflow run — no setup required
• Expires when the job completes or after 24 hours, whichever comes first
• Default permissions depend on repository settings: either read & write (permissive) or read-only (restrictive)
• Principle of least privilege: always restrict permissions to only what the job needs

Restricting Permissions

Declare a permissions block at the workflow or job level. Any scope not listed is automatically set to none:

# Workflow-level — applies to ALL jobs
permissions:
  contents: read
  packages: write
  pull-requests: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Token can read code, write packages, write PR comments
      # Everything else (issues, deployments, etc.) = none

# Job-level — overrides workflow-level for this job only
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # Needed for OIDC
    steps:
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

Available Permission Scopes

Setting Default to Read-Only

At the organization or repository level, navigate to Settings → Actions → General → Workflow permissions and select "Read repository contents and packages permissions". This forces all workflows to start with read-only access — individual workflows must explicitly opt-in to write permissions.

🌐 OIDC Federation

OpenID Connect (OIDC) lets your workflow exchange GitHub's built-in JWT for short-lived cloud credentials — no stored secrets required.

Why OIDC?

• No long-lived secrets — nothing to rotate, nothing to leak
• Automatic rotation — tokens are generated fresh for every workflow run
• Fine-grained trust — cloud providers validate the JWT claims (repo, branch, environment) before issuing credentials

How It Works

┌──────────────┐       ┌──────────────────────┐       ┌─────────────────┐
│  GitHub       │  1.   │  GitHub OIDC          │  3.   │  Cloud Provider  │
│  Workflow     │──────▶│  Provider             │◀──────│  IAM             │
│  (requests    │       │  (issues JWT with     │       │  (validates JWT, │
│   id-token)   │       │   repo/branch/env     │       │   checks claims, │
│               │  2.   │   claims)             │  4.   │   issues creds)  │
│               │◀──────│                       │──────▶│                  │
└──────────────┘  JWT   └──────────────────────┘       └────────┬────────┘
       │                                                        │
       │  5. Short-lived credentials                            │
       │◀───────────────────────────────────────────────────────┘
       │
       ▼
  Deploy / Push / Access Cloud Resources

Azure Setup

1. App Registration — create (or reuse) an app in Azure AD
2. Federated Credential — add a credential that trusts GitHub's OIDC provider
3. Subject claim — scope to specific repo, branch, or environment

# Create federated credential for main branch
az ad app federated-credential create \
  --id <APP_OBJECT_ID> \
  --parameters '{
    "name": "github-main",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main",
    "audiences": ["api://AzureADTokenExchange"]
  }'

AWS Setup

1. IAM Identity Provider — add token.actions.githubusercontent.com as an OIDC provider
2. IAM Role — create a role that trusts the OIDC provider
3. Trust condition — restrict to your repo using sub claim

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
        "token.actions.githubusercontent.com:sub": "repo:myorg/myrepo:ref:refs/heads/main"
      }
    }
  }]
}

GCP Setup

1. Workload Identity Pool — create a pool for GitHub Actions
2. Provider — add an OIDC provider pointing to GitHub
3. Service Account binding — bind the pool to a GCP service account with appropriate roles

# Create workload identity pool
gcloud iam workload-identity-pools create github-pool \
  --location="global" --display-name="GitHub Actions Pool"

# Create OIDC provider
gcloud iam workload-identity-pools providers create-oidc github-provider \
  --location="global" \
  --workload-identity-pool="github-pool" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository"

# Bind service account
gcloud iam service-accounts add-iam-policy-binding deploy-sa@myproject.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/<PROJECT_NUM>/locations/global/workloadIdentityPools/github-pool/attribute.repository/myorg/myrepo"

Subject Claims

Subject claims control exactly which workflows can request tokens. Use these to enforce fine-grained trust:

🛡️ Branch Protection & Rulesets

Branch protection ensures that code reaching your main branch (and triggering deployments) has been reviewed, tested, and verified.

Required Status Checks

• Specify which workflow jobs must pass before a PR can be merged
• Prevents broken or untested code from reaching production branches
• Configure via Settings → Branches → Add rule → Require status checks to pass

Required Reviews

• Enforce a minimum number of approving reviews (1, 2, or more)
• Optionally require review from code owners (CODEOWNERS file)
• Dismiss stale reviews when new commits are pushed

Signed Commits

• Require all commits in a PR to be GPG or SSH signed
• Ensures the committer's identity is cryptographically verified
• Prevents impersonation and unauthorized commits

GitHub Rulesets (New)

Rulesets are the next generation of branch protection — more flexible and stack-able:

• Stack-able: multiple rulesets can apply to the same branch — their rules are combined
• Bypass list: designate specific teams or apps that can bypass rules (e.g., release bots)
• Tag rules: protect tags the same way you protect branches
• Organization-level: enforce rules across all repos from a single config

How to enforce:
1. Navigate to Settings → Rules → Rulesets → New ruleset
2. Name the ruleset (e.g., "Production Protection")
3. Target: branches matching "main", "release/*"
4. Rules: Require status checks, Require pull request, Require signed commits
5. Bypass: Add "release-bot" app
6. Enforcement: Active

📦 Supply Chain Security

Your workflow is only as secure as the actions it consumes. A compromised third-party action can steal secrets, inject malicious code, or exfiltrate data.

Pin Actions by SHA

Never reference actions by mutable tag — always pin to a specific commit SHA:

# ❌ BAD — tag can be moved to a malicious commit
- uses: actions/checkout@v4

# ✅ GOOD — pinned to an immutable commit SHA
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1

Add a comment with the version tag for readability. The SHA is immutable — even if the tag is moved, your workflow runs the exact code you audited.

Dependabot for Actions

Automate SHA updates by adding a dependabot.yml to your repository:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Dependabot will open PRs when new versions of pinned actions are available, including the updated SHA.

SLSA Provenance & Attestations

• SLSA (Supply-chain Levels for Software Artifacts) is a framework for ensuring build integrity
• Provenance records who built what, when, where, and how — cryptographically signed
• Use actions/attest-build-provenance to generate attestations for your build outputs

permissions:
  id-token: write
  contents: read
  attestations: write

steps:
  - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
  - name: Build artifact
    run: npm run build
  - uses: actions/attest-build-provenance@v2
    with:
      subject-path: 'dist/'

Private Action Restrictions

• At the org level, restrict which actions can be used: Settings → Actions → General → Actions permissions
• Options: allow all, allow only local actions, allow select actions (allow-list)
• Enterprise orgs should maintain a curated allow-list of vetted actions

Fork Pull Request Restrictions

• Workflows triggered by fork PRs run with read-only permissions and no access to secrets by default
• Require approval before running workflows from first-time contributors
• Configure: Settings → Actions → General → Fork pull request workflows
• Never auto-approve fork PR workflows — a malicious PR can exfiltrate secrets if workflows have write permissions

✅ Security Hardening Checklist

📊 OIDC Authentication Flow

┌──────────────┐    ┌──────────────────────┐    ┌──────────────────┐
│              │ 1. │                      │    │                  │
│   Workflow   │───▶│  Request id-token    │    │   Cloud IAM      │
│   Job Starts │    │  from GITHUB_TOKEN   │    │   (Azure / AWS   │
│              │    │                      │    │    / GCP)         │
└──────────────┘    └──────────┬───────────┘    └────────┬─────────┘
                               │                         │
                          2. Request                 4. Validate
                               │                      JWT claims
                               ▼                         │
                    ┌──────────────────────┐             │
                    │   GitHub OIDC        │  3. Present │
                    │   Provider           │────JWT─────▶│
                    │   (issues JWT with   │             │
                    │    repo, branch,     │             │
                    │    env claims)       │             │
                    └──────────────────────┘             │
                                                         │
                    ┌──────────────────────┐  5. Issue   │
                    │   Short-lived        │◀────────────┘
                    │   Cloud Credentials  │
                    └──────────┬───────────┘
                               │
                          6. Use credentials
                               │
                               ▼
                    ┌──────────────────────┐
                    │   Deploy / Push /    │
                    │   Access Resources   │
                    └──────────────────────┘

🛠️ Hands-on Lab

Lab 1: Set Default Permissions to Read-Only

1. Navigate to your repository Settings → Actions → General
2. Under Workflow permissions, select "Read repository contents and packages permissions"
3. Save — all existing workflows now run with read-only tokens unless they explicitly declare permissions
4. Test: trigger a workflow that writes (e.g., creates a comment). Observe the 403 failure, then add the required permissions block

Lab 2: Configure GITHUB_TOKEN Scoping

1. Create a workflow with a job that comments on a PR:

name: PR Comment
on: pull_request

permissions:
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: 'CI checks are running!'
            })

2. Open a PR and verify the comment appears
3. Remove the permissions block — observe the failure when the default is read-only

Lab 3: Pin an Action by SHA

1. Visit the action's repository on GitHub (e.g., actions/checkout)
2. Find the latest release tag (e.g., v4.1.1) and copy the full commit SHA from the tag
3. Replace uses: actions/checkout@v4 with uses: actions/checkout@<FULL_SHA> # v4.1.1
4. Add a .github/dependabot.yml for github-actions to receive update PRs

Lab 4: Set Up Required Status Checks

1. Create a workflow that runs tests on every PR
2. Navigate to Settings → Branches → Add rule for main
3. Enable "Require status checks to pass before merging"
4. Search for and select your workflow's job name (e.g., test)
5. Open a PR with a failing test — verify that GitHub blocks the merge

🐛 Debugging Common Issues

"Resource not accessible by integration"

• Cause: The GITHUB_TOKEN doesn't have the required permission scope
• Fix: Add the missing scope to the permissions block. For example, if you're creating PR comments, add pull-requests: write. If creating releases, add contents: write
• Check: Verify the org/repo default isn't overriding your workflow permissions — go to Settings → Actions → General → Workflow permissions

"OIDC token audience mismatch"

• Cause: The audience (aud) claim in the JWT doesn't match what the cloud provider expects
• Fix (Azure): Ensure the federated credential's audience is api://AzureADTokenExchange
• Fix (AWS): Ensure the OIDC provider audience is sts.amazonaws.com
• Debugging: Print the token to inspect claims: curl -s "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" | jq -R 'split(".") | .[1] | @base64d | fromjson'

"Status check not found" in branch protection

• Cause: The status check name doesn't match the workflow's name + job name combination
• Fix: Branch protection looks for <workflow_name> / <job_name>. If your workflow is named CI and the job is test, the status check is CI / test. Ensure you select this exact name when configuring required checks
• Tip: Run the workflow at least once before configuring the branch protection rule — GitHub won't show status checks it hasn't seen yet

🎯 Interview Questions

Basic (5)

Intermediate (5)

Senior (5)

🏭 Real-World Scenario

A mid-size SaaS company preparing for SOC 2 Type II certification needed to prove their CI/CD pipeline met strict security controls. Here's how they hardened their GitHub Actions setup:

Before (audit findings):

• All workflows ran with read-write GITHUB_TOKEN by default
• Actions referenced by tag (@v4) with no SHA pinning
• Azure Service Principal secrets stored in 30+ repositories with no rotation schedule
• No branch protection — any developer could push directly to main
• No audit trail for who deployed what and when

After (remediation):

• Org-wide read-only default — every workflow must explicitly declare write permissions. SOC 2 Control: AC-6 (Least Privilege)
• SHA pinning + Dependabot — all 200+ action references pinned by SHA. Dependabot opens weekly PRs for updates. SOC 2 Control: SA-22 (Supply Chain)
• OIDC federation only — deleted all stored Azure/AWS secrets. Federated credentials scoped to environment:production. SOC 2 Control: IA-5 (Authenticator Management)
• Rulesets enforced at org level — required 2 reviews, required status checks (lint + test + security scan), signed commits. SOC 2 Control: CM-3 (Change Control)
• Audit log streaming — all workflow runs, permission changes, and deployment events streamed to Splunk SIEM with 90-day retention. SOC 2 Control: AU-6 (Audit Review)
• SLSA provenance — every production artifact attested with actions/attest-build-provenance. SOC 2 Control: SI-7 (Software Integrity)

Result: passed SOC 2 audit with zero findings on the CI/CD pipeline. Mean time to rotate compromised credentials dropped from 2 days to zero (nothing to rotate with OIDC).

📝 Summary

• GITHUB_TOKEN: Auto-generated, short-lived token. Always restrict with explicit permissions blocks. Set org/repo default to read-only
• OIDC: Exchange GitHub's JWT for short-lived cloud credentials. No stored secrets, automatic rotation, fine-grained trust via subject claims
• Branch protection: Required status checks, required reviews, signed commits. Use Rulesets for stackable, org-level enforcement
• Supply chain: Pin actions by SHA, enable Dependabot for updates, generate SLSA provenance, maintain an org-level allow-list
• Fork PRs: Read-only token, no secrets by default. Require approval. Never use pull_request_target to run untrusted code
• Hardening: Follow the 10-point checklist — defence in depth means multiple overlapping security controls