GitHub Actions Secrets 指南：GITHUB_TOKEN、gh secret set、OIDC 与 if 条件

GitHub Actions 密钥允许你在仓库设置中安全存储敏感数据——API 密钥、密码、令牌、证书——并在工作流中使用它们，而无需在代码中暴露。本指南涵盖从基本密钥使用到高级模式（如 OIDC 联合认证、环境范围密钥和自动轮换）的所有内容。

# Create or update a repository secret
gh secret set API_TOKEN --body "$API_TOKEN"

# Create an environment-scoped secret for production deploys
gh secret set DATABASE_URL --env production --body "$DATABASE_URL"

# Create an organization secret and limit it to selected repositories
gh secret set SENTRY_AUTH_TOKEN \
  --org ORG_NAME \
  --repos web-app,api-service \
  --body "$SENTRY_AUTH_TOKEN"

# List configured secret names without revealing values
gh secret list
gh secret list --env production
gh secret list --org ORG_NAME

# Use the automatic GITHUB_TOKEN with least privilege
permissions:
  contents: read
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: 'CI completed.'
            })

# Secrets cannot be referenced directly in if:
# Move the value into an env var, then test the env var.
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      HAS_DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN != '' }}
    steps:
      - name: Deploy only when the secret exists
        if: env.HAS_DEPLOY_TOKEN == 'true'
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: ./deploy.sh

基本密钥使用

密钥在仓库设置（Settings > Secrets and variables > Actions）中定义，并在工作流中使用 secrets 上下文引用。它们在工作流日志中自动被遮蔽。

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

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

      - name: Deploy to server
        env:
          # Reference a repository secret
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          echo "Deploying with secure credentials..."
          ./deploy.sh

环境范围的密钥

GitHub Environments 允许你定义特定于部署环境（staging、production）的密钥，并添加保护规则，如必要的审查者。

# Environment-specific secrets (staging vs production)
name: Deploy

on:
  push:
    branches: [main, staging]

jobs:
  deploy:
    runs-on: ubuntu-latest
    # Pick environment based on branch
    environment: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}

    steps:
      - uses: actions/checkout@v4

      - name: Deploy
        env:
          # These come from the selected environment's secrets
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: ./deploy.sh --env ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}

OIDC 联合认证：无需长期密钥

2026 年的最佳实践是使用 OIDC（OpenID Connect）联合认证来与云提供商进行身份验证，而不是存储长期访问密钥。GitHub Actions 可以将 JWT 令牌交换为临时云凭证。

# OIDC: No long-lived credentials needed!
name: Deploy to AWS (OIDC)

on:
  push:
    branches: [main]

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

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

      - 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
          # No ACCESS_KEY or SECRET_KEY secrets needed!

      - name: Deploy to S3
        run: aws s3 sync ./dist s3://my-bucket --delete

密钥遮蔽和安全使用

GitHub 自动在日志中遮蔽密钥值，但有一些重要的注意事项需要了解以避免意外暴露。

# Secrets are automatically masked in logs
# But be careful with derived values!

jobs:
  careful:
    runs-on: ubuntu-latest
    steps:
      - name: Use secret safely
        env:
          MY_SECRET: ${{ secrets.MY_SECRET }}
        run: |
          # This output will be masked: ***
          echo "Secret value: $MY_SECRET"

          # DANGER: This may expose the secret!
          # If MY_SECRET="abc", base64 gives "YWJj" which is NOT masked
          echo $MY_SECRET | base64

          # Safe: always use secrets directly, not derived forms
          curl -H "Authorization: Bearer $MY_SECRET" https://api.example.com/endpoint

      - name: Add to mask (for dynamic secrets)
        run: |
          # Manually mask a dynamically generated value
          TOKEN=$(generate-token.sh)
          echo "::add-mask::${TOKEN}"
          echo "TOKEN=${TOKEN}" >> $GITHUB_ENV

可复用工作流中的密钥

使用可复用工作流（workflow_call）时，密钥必须通过 secrets 映射显式传递，或用 secrets: inherit 有意转发。不要假设被调用工作流会自动拿到凭证。

# .github/workflows/reusable-deploy.yml
name: Reusable Deploy Workflow

on:
  workflow_call:
    secrets:
      DEPLOY_KEY:
        required: true
      DATABASE_URL:
        required: true
      SLACK_WEBHOOK:
        required: false

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

      - name: Deploy
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: ./deploy.sh

      - name: Notify Slack
        if: ${{ secrets.SLACK_WEBHOOK != '' }}
        run: |
          curl -X POST -H 'Content-type: application/json' \
            --data '{"text":"Deployment complete!"}' \
            ${{ secrets.SLACK_WEBHOOK }}

# .github/workflows/production.yml — caller
name: Production Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: ./.github/workflows/reusable-deploy.yml
    secrets:
      DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
      DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}
      SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}

  # Alternative for trusted same-organization workflows:
  # deploy:
  #   uses: org/reusable/.github/workflows/deploy.yml@main
  #   secrets: inherit

自动密钥轮换

长期密钥是安全风险。使用计划工作流设置自动轮换。

# Automated secret rotation pattern
name: Rotate API Token

on:
  schedule:
    - cron: '0 0 1 * *'  # Monthly rotation
  workflow_dispatch:       # Manual trigger

jobs:
  rotate:
    runs-on: ubuntu-latest
    steps:
      - name: Generate new token
        id: generate
        env:
          OLD_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          # Call API to generate new token using old token
          NEW_TOKEN=$(curl -s -X POST \
            -H "Authorization: Bearer $OLD_TOKEN" \
            https://api.example.com/tokens/rotate | jq -r '.token')
          echo "::add-mask::${NEW_TOKEN}"
          echo "new_token=${NEW_TOKEN}" >> $GITHUB_OUTPUT

      - name: Update GitHub secret
        uses: gliech/create-github-secret-action@v1
        with:
          name: API_TOKEN
          value: ${{ steps.generate.outputs.new_token }}
          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

密钥存储选项对比

安全最佳实践

1. 尽可能对云提供商（AWS、GCP、Azure）使用 OIDC 联合认证，而不是静态访问密钥。
2. 将密钥限定在环境范围内。生产密钥应需要环境保护规则（必要的审查者、部署分支）。
3. 永远不要在工作流步骤中打印密钥，即使是用于调试。GitHub 遮蔽确切的字符串，但编码/转换会绕过遮蔽。
4. 定期轮换密钥。为 API 密钥设置日历提醒或使用自动轮换工作流。
5. 使用所需的最小权限。专门为 GitHub Actions 创建具有狭窄范围的服务账户。
6. 通过 GitHub 的审计日志审计密钥访问。检查哪些工作流在使用哪些密钥。

常见问题