Secrets & Variables

Securely manage credentials, API keys, and configuration across repository, environment, and organization scopes.

🧒 Simple Explanation (ELI5)

Imagine you're staying at a hotel.

• Secrets are like your passport and cash — you lock them in the hotel safe. Nobody can see what's inside, not even housekeeping. When you need them, you unlock the safe, use them, and put them back. If someone asks "what's in the safe?", the hotel says "I can't tell you." That's how GitHub secrets work — encrypted, invisible even to admins after creation, and automatically masked in logs.
• Variables are like the items on your desk — your itinerary, a map, your conference badge. Anyone who walks in can see them, and that's fine because they're not sensitive. Variables store non-secret config like API base URLs or feature flags.
• Environment secrets are like having different safes in different rooms. The staging room has test API keys, the production room has real ones. When you check into a room (deploy to an environment), you only get that room's safe.

GitHub Actions gives you three levels of safes (organization → repository → environment) so the right credentials are available to the right workflows at the right time — and nothing more.

🔐 Repository Secrets

Repository secrets are the most common way to store sensitive values. They're scoped to a single repository and available to all workflows in that repo.

Creating a Repository Secret

1. Go to your repository → Settings → Secrets and variables → Actions
2. Click New repository secret
3. Enter a name (e.g., ACR_PASSWORD) and the secret value
4. Click Add secret

Using Secrets in Workflows

steps:
  - name: Login to ACR
    uses: azure/docker-login@v1
    with:
      login-server: ${{ secrets.ACR_LOGIN_SERVER }}
      username: ${{ secrets.ACR_USERNAME }}
      password: ${{ secrets.ACR_PASSWORD }}

  - name: Use secret in a run step
    env:
      DB_CONNECTION: ${{ secrets.DATABASE_URL }}
    run: echo "Connecting to database..."

🌍 Environment Secrets

Environment secrets are scoped to a specific deployment environment (e.g., staging, production). They override repository secrets with the same name, and they're only available when a job explicitly references that environment.

Setting Up Environments

1. Go to Settings → Environments → New environment
2. Name it (e.g., production)
3. Add protection rules: required reviewers, wait timers, branch restrictions
4. Add environment-specific secrets and variables

Using Environment Secrets

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging          # Uses staging secrets
    steps:
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}    # staging API key
        run: ./deploy.sh

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production       # Uses production secrets
    steps:
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}    # production API key (different value!)
        run: ./deploy.sh

🏢 Organization Secrets

Organization secrets are shared across multiple repositories. They're ideal for credentials that many repos need — like a shared container registry password or a monitoring API key.

Visibility Policies

• All repositories — every repo in the org can access the secret
• Private repositories — only private repos can access it (excludes public/internal repos)
• Selected repositories — you explicitly pick which repos get access

Creating Organization Secrets

Go to your organization → Settings → Secrets and variables → Actions → New organization secret. Choose the visibility policy and save.

📋 Variables (Not Secret)

Variables store non-sensitive configuration values. Unlike secrets, they're visible in logs and can be read back from the UI. Use them for API base URLs, feature flags, version numbers, and environment names.

Creating Variables

Go to Settings → Secrets and variables → Actions → Variables tab → New repository variable. Variables also support repository, environment, and organization scopes — the same hierarchy as secrets.

Using Variables in Workflows

env:
  APP_ENV: ${{ vars.ENVIRONMENT_NAME }}
  API_URL: ${{ vars.API_BASE_URL }}
  FEATURE_NEW_UI: ${{ vars.FEATURE_NEW_UI }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Show config
        run: |
          echo "Deploying to: ${{ vars.ENVIRONMENT_NAME }}"
          echo "API endpoint: ${{ vars.API_BASE_URL }}"
          echo "New UI enabled: ${{ vars.FEATURE_NEW_UI }}"

🪪 OIDC (OpenID Connect) — Passwordless Cloud Auth

OIDC eliminates the need for stored cloud credentials entirely. Instead of long-lived secrets, GitHub Actions requests short-lived tokens directly from your cloud provider. No secrets to rotate, no credentials to leak.

How OIDC Works

┌─────────────────────┐     1. Request OIDC token     ┌─────────────────────┐
│                     │ ─────────────────────────────▶ │                     │
│   GitHub Actions    │                                │   GitHub OIDC       │
│   Workflow          │ ◀───────────────────────────── │   Provider          │
│                     │     2. Return signed JWT       │                     │
└────────┬────────────┘                                └─────────────────────┘
         │
         │  3. Present JWT to cloud provider
         ▼
┌─────────────────────┐                                ┌─────────────────────┐
│                     │     4. Validate JWT issuer     │                     │
│   Cloud Provider    │ ─────────────────────────────▶ │   Trust Policy      │
│   (Azure/AWS/GCP)   │                                │   (Federated Cred)  │
│                     │ ◀───────────────────────────── │                     │
│                     │     5. Issue short-lived token  │                     │
└─────────────────────┘                                └─────────────────────┘
         │
         │  6. Use short-lived token to access resources
         ▼
┌─────────────────────┐
│   Cloud Resources   │
│   (ACR, AKS, S3...) │
└─────────────────────┘

Azure OIDC Example

Prerequisites: Create a federated credential on your Azure AD app registration that trusts your GitHub repo.

name: Deploy with OIDC
on:
  push:
    branches: [main]

permissions:
  id-token: write        # Required for OIDC
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Azure Login (OIDC — no secrets needed!)
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

      - name: Deploy to AKS
        run: |
          az aks get-credentials --resource-group myRG --name myAKS
          kubectl apply -f k8s/

AWS OIDC Example

Prerequisites: Create an IAM OIDC identity provider for token.actions.githubusercontent.com and a role with a trust policy scoped to your repo.

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: us-east-1

      - name: Push to ECR
        run: |
          aws ecr get-login-password | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
          docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:${{ github.sha }}

💻 Code Examples — Secrets vs OIDC

Here's a side-by-side comparison of the traditional (stored credentials) vs modern (OIDC) approach:

Traditional — Stored Credentials

# ❌ Traditional: secrets that need rotation
- name: Login to ACR
  uses: azure/docker-login@v1
  with:
    login-server: ${{ secrets.ACR_LOGIN_SERVER }}
    username: ${{ secrets.ACR_USERNAME }}
    password: ${{ secrets.ACR_PASSWORD }}

Modern — OIDC (No Secrets Needed)

# ✅ Modern: OIDC — no stored credentials
- name: Azure Login (OIDC)
  uses: azure/login@v2
  with:
    client-id: ${{ vars.AZURE_CLIENT_ID }}
    tenant-id: ${{ vars.AZURE_TENANT_ID }}
    subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

- name: Login to ACR via OIDC
  run: az acr login --name myregistry

📊 Secret & Variable Hierarchy

When the same secret name exists at multiple levels, the most specific scope wins: environment overrides repository, which overrides organization.

📐 Secret Resolution Flow

  ${{ secrets.API_KEY }} referenced in a workflow step
                    │
                    ▼
  ┌─────────────────────────────────────┐
  │  Does the job have `environment:`?  │
  │  e.g., environment: production      │
  └──────────┬──────────────┬───────────┘
             │ YES          │ NO
             ▼              │
  ┌──────────────────┐      │
  │  Environment has  │      │
  │  API_KEY secret?  │      │
  └──┬───────────┬───┘      │
     │ YES       │ NO       │
     ▼           ▼          ▼
  ┌────────┐  ┌─────────────────────┐
  │ USE IT │  │  Repository has      │
  │ (done) │  │  API_KEY secret?     │
  └────────┘  └──┬──────────────┬───┘
                 │ YES          │ NO
                 ▼              ▼
           ┌────────┐  ┌─────────────────────┐
           │ USE IT │  │  Organization has    │
           │ (done) │  │  API_KEY secret?     │
           └────────┘  └──┬──────────────┬───┘
                          │ YES          │ NO
                          ▼              ▼
                    ┌────────┐    ┌────────────┐
                    │ USE IT │    │ Empty string│
                    │ (done) │    │ (not found) │
                    └────────┘    └────────────┘

🛠️ Hands-on Exercises

🐛 Common Issues & Debugging

Secret Is Empty

Error: Input required and not supplied: password

Cause: Wrong secret name, wrong case (though names are case-insensitive, typos happen), or the secret doesn't exist at the scope the job is using.

Fix: Double-check the name in Settings → Secrets and variables. If using environment secrets, make sure the job has environment: set. For fork PRs, note that secrets are not available in workflows triggered by pull requests from forks — this is a security feature to prevent exfiltration.

Secret Value Visible in Logs

Cause: The secret was used in a URL (https://user:${{ secrets.TOKEN }}@github.com), base64 encoded, or split across multiple echo statements where individual characters don't trigger masking.

Fix: Never embed secrets in URLs directly. Use git config or environment variables instead. For base64-encoded values, GitHub masks the original but may not catch the encoded form if it's generated at runtime. Always pass secrets through env: blocks rather than inline in run: commands.

OIDC Token Request Fails

Error: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable

Cause: Missing permissions: id-token: write on the job or workflow.

Fix: Add permissions: { id-token: write, contents: read }. When you set any permission explicitly, all other permissions default to none — so you must also add contents: read for checkout to work.

Environment Secret Not Overriding Repo Secret

Cause: The job doesn't declare environment: <name>, so it uses the repo-level secret.

Fix: Add environment: production (or the appropriate name) to the job definition. Environment secrets only take effect when the job explicitly targets that environment.

🎯 Interview Questions

Beginner (B1–B5)

Intermediate (I1–I5)

Senior (S1–S5)

🌍 Real-World Scenario: Migrating from Stored Credentials to OIDC

A SaaS company running on Azure has 40 repositories deploying to AKS. Each repo stores three secrets — AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID — for a total of 120 stored credentials. Every 90 days, the security team rotates all client secrets manually. This process takes two days and has caused three production outages from missed rotations in the past year.

The Migration

1. Created federated credentials in Azure AD for each repo, scoped to main branch and production environment
2. Converted secrets to variables — client ID and tenant ID moved from secrets. to vars. (they're not sensitive with OIDC)
3. Removed client secrets entirely — no more AZURE_CLIENT_SECRET in any repo
4. Added permissions: id-token: write to deployment jobs
5. Switched from azure/login@v1 to azure/login@v2 with OIDC parameters

Results

• 120 → 0 stored credentials — nothing to rotate, nothing to leak
• Zero rotation-related outages since migration — no more expired secrets
• Tokens live for 10 minutes — even if leaked, they expire before they can be exploited
• Audit trail — Azure logs show exactly which repo and workflow assumed the identity
• Security team reclaimed 2 days/quarter previously spent on manual secret rotation

📝 Summary

• Repository secrets store sensitive values encrypted at rest, masked in logs, and inaccessible after creation
• Environment secrets scope credentials to specific deployment targets (staging, production) with optional protection rules
• Organization secrets share credentials across repos with configurable visibility policies — update once, apply everywhere
• Variables (vars.) store non-sensitive config — visible in logs, readable from the UI, ideal for URLs and feature flags
• Precedence: Environment > Repository > Organization — the most specific scope always wins
• OIDC eliminates stored credentials entirely — short-lived tokens, no rotation, auditable trust chain
• Secrets are not available in fork PRs — this is a security feature, not a bug
• Never embed secrets in URLs or concatenate them into strings that bypass masking
• Use permissions: id-token: write at the job level for OIDC, and scope cloud trust policies to specific repos and branches
• Prefer OIDC over stored credentials for any cloud provider that supports it — it's more secure and less operational burden