GitHub Actions 手动触发 #

手动触发允许你在需要时启动工作流，适用于部署、测试等需要人工确认的场景。本节详细介绍手动触发的配置和使用。

workflow_dispatch事件 #

基本用法 #

yaml 
on: workflow_dispatch

最简单的手动触发，无需任何参数。

带输入参数 #

yaml 
on:
  workflow_dispatch:
    inputs:
      name:
        description: 'Your name'
        required: true
        default: 'World'

输入参数类型 #

string类型 #

yaml 
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy'
        required: true
        type: string
        default: '1.0.0'

choice类型 #

yaml 
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy environment'
        required: true
        type: choice
        default: 'staging'
        options:
          - staging
          - production

boolean类型 #

yaml 
on:
  workflow_dispatch:
    inputs:
      debug:
        description: 'Enable debug mode'
        required: false
        type: boolean
        default: false

environment类型 #

yaml 
on:
  workflow_dispatch:
    inputs:
      target:
        description: 'Target environment'
        required: true
        type: environment

完整输入配置 #

yaml 
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy environment'
        required: true
        type: choice
        default: 'staging'
        options:
          - staging
          - production
      
      version:
        description: 'Version to deploy'
        required: true
        type: string
        default: 'latest'
      
      debug:
        description: 'Enable debug mode'
        required: false
        type: boolean
        default: false
      
      dry-run:
        description: 'Dry run mode'
        required: false
        type: boolean
        default: false
      
      tags:
        description: 'Deployment tags (comma separated)'
        required: false
        type: string

使用输入参数 #

在步骤中使用 #

yaml 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Display inputs
        run: |
          echo "Environment: ${{ github.event.inputs.environment }}"
          echo "Version: ${{ github.event.inputs.version }}"
          echo "Debug: ${{ github.event.inputs.debug }}"
          echo "Dry run: ${{ github.event.inputs.dry-run }}"

条件执行 #

yaml 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Debug step
        if: github.event.inputs.debug == 'true'
        run: echo "Debug mode enabled"
      
      - name: Deploy to staging
        if: github.event.inputs.environment == 'staging'
        run: ./deploy.sh staging
      
      - name: Deploy to production
        if: github.event.inputs.environment == 'production'
        run: ./deploy.sh production

在环境中使用 #

yaml 
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_ENV: ${{ github.event.inputs.environment }}
      VERSION: ${{ github.event.inputs.version }}
    steps:
      - run: |
          echo "Deploying $VERSION to $DEPLOY_ENV"

触发方式 #

通过GitHub网页 #

  1. 进入仓库的 “Actions” 标签
  2. 选择工作流
  3. 点击 “Run workflow”
  4. 填写输入参数
  5. 点击 “Run workflow”

通过GitHub CLI #

bash 
# 无参数触发
gh workflow run workflow-name

# 带参数触发
gh workflow run workflow-name \
  -f environment=production \
  -f version=1.0.0 \
  -f debug=true

# 使用JSON格式
gh workflow run workflow-name \
  -f environment=production \
  -F inputs='{"version":"1.0.0","debug":true}'

通过API触发 #

bash 
curl -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/owner/repo/actions/workflows/workflow.yml/dispatches \
  -d '{
    "ref": "main",
    "inputs": {
      "environment": "production",
      "version": "1.0.0",
      "debug": "true"
    }
  }'

实际应用示例 #

部署工作流 #

yaml 
name: Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment'
        required: true
        type: choice
        options:
          - staging
          - production
        default: 'staging'
      
      version:
        description: 'Version (leave empty for latest)'
        required: false
        type: string
      
      skip-tests:
        description: 'Skip tests'
        required: false
        type: boolean
        default: false

jobs:
  test:
    if: github.event.inputs.skip-tests != 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    if: always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment }}
    steps:
      - uses: actions/checkout@v4
      
      - name: Get version
        id: version
        run: |
          if [ -n "${{ github.event.inputs.version }}" ]; then
            echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
          else
            echo "version=latest" >> $GITHUB_OUTPUT
          fi
      
      - name: Deploy
        run: |
          echo "Deploying version ${{ steps.version.outputs.version }}"
          echo "Environment: ${{ github.event.inputs.environment }}"
          ./deploy.sh ${{ github.event.inputs.environment }} ${{ steps.version.outputs.version }}
      
      - name: Notify
        if: success()
        run: echo "Deployment successful"

回滚工作流 #

yaml 
name: Rollback

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment'
        required: true
        type: choice
        options:
          - staging
          - production
      
      version:
        description: 'Version to rollback to'
        required: true
        type: string
      
      reason:
        description: 'Rollback reason'
        required: true
        type: string

jobs:
  rollback:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment }}
    steps:
      - uses: actions/checkout@v4
      
      - name: Rollback
        run: |
          echo "Rolling back to version ${{ github.event.inputs.version }}"
          echo "Reason: ${{ github.event.inputs.reason }}"
          ./rollback.sh ${{ github.event.inputs.environment }} ${{ github.event.inputs.version }}
      
      - name: Create issue
        uses: peter-evans/create-issue-from-file@v4
        with:
          title: "Rollback: ${{ github.event.inputs.environment }} to ${{ github.event.inputs.version }}"
          content: |
            ## Rollback Details
            
            - **Environment**: ${{ github.event.inputs.environment }}
            - **Version**: ${{ github.event.inputs.version }}
            - **Reason**: ${{ github.event.inputs.reason }}
            - **Triggered by**: ${{ github.actor }}
          labels: rollback

数据库迁移 #

yaml 
name: Database Migration

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment'
        required: true
        type: choice
        options:
          - staging
          - production
      
      migration:
        description: 'Migration file'
        required: true
        type: string
      
      dry-run:
        description: 'Dry run'
        required: false
        type: boolean
        default: true

jobs:
  migrate:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment }}
    steps:
      - uses: actions/checkout@v4
      
      - name: Run migration
        run: |
          if [ "${{ github.event.inputs.dry-run }}" == "true" ]; then
            echo "Dry run mode"
            ./migrate.sh --dry-run ${{ github.event.inputs.migration }}
          else
            ./migrate.sh ${{ github.event.inputs.migration }}
          fi

批量操作 #

yaml 
name: Batch Operation

on:
  workflow_dispatch:
    inputs:
      operation:
        description: 'Operation type'
        required: true
        type: choice
        options:
          - cleanup
          - rebuild
          - sync
      
      targets:
        description: 'Targets (comma separated)'
        required: true
        type: string
      
      force:
        description: 'Force operation'
        required: false
        type: boolean
        default: false

jobs:
  batch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Parse targets
        id: targets
        run: |
          IFS=',' read -ra TARGETS <<< "${{ github.event.inputs.targets }}"
          echo "targets=$(printf '%s\n' "${TARGETS[@]}" | jq -R . | jq -s .)" >> $GITHUB_OUTPUT
      
      - name: Execute operation
        run: |
          for target in $(echo '${{ steps.targets.outputs.targets }}' | jq -r '.[]'); do
            echo "Processing: $target"
            ./operation.sh ${{ github.event.inputs.operation }} $target ${{ github.event.inputs.force == 'true' && '--force' || '' }}
          done

高级用法 #

动态输入验证 #

yaml 
jobs:
  validate:
    runs-on: ubuntu-latest
    outputs:
      valid: ${{ steps.validate.outputs.valid }}
    steps:
      - id: validate
        run: |
          if [[ "${{ github.event.inputs.version }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "valid=true" >> $GITHUB_OUTPUT
          else
            echo "valid=false" >> $GITHUB_OUTPUT
            echo "::error::Invalid version format"
          fi

  deploy:
    needs: validate
    if: needs.validate.outputs.valid == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying..."

多阶段确认 #

yaml 
jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      should_continue: ${{ steps.confirm.outputs.continue }}
    steps:
      - id: confirm
        run: |
          echo "Environment: ${{ github.event.inputs.environment }}"
          echo "Version: ${{ github.event.inputs.version }}"
          echo "Continue with deployment? (This is a dry run check)"
          echo "continue=true" >> $GITHUB_OUTPUT

  deploy:
    needs: prepare
    if: needs.prepare.outputs.should_continue == 'true'
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment }}
    steps:
      - run: ./deploy.sh

使用矩阵 #

yaml 
on:
  workflow_dispatch:
    inputs:
      environments:
        description: 'Environments (comma separated)'
        required: true
        default: 'staging,production'

jobs:
  deploy:
    strategy:
      matrix:
        environment: ${{ fromJSON(format('["{0}"]', join(split(github.event.inputs.environments, ','), '","'))) }}
    runs-on: ubuntu-latest
    environment: ${{ matrix.environment }}
    steps:
      - run: echo "Deploying to ${{ matrix.environment }}"

最佳实践 #

1. 提供清晰的描述 #

yaml 
inputs:
  environment:
    description: 'Target environment for deployment (staging or production)'
    required: true

2. 设置合理的默认值 #

yaml 
inputs:
  debug:
    description: 'Enable debug mode'
    default: false
    type: boolean

3. 使用choice限制选项 #

yaml 
inputs:
  environment:
    type: choice
    options:
      - staging
      - production

4. 添加确认步骤 #

yaml 
steps:
  - name: Confirm deployment
    run: |
      echo "About to deploy to ${{ github.event.inputs.environment }}"
      echo "Version: ${{ github.event.inputs.version }}"
      echo "Triggered by: ${{ github.actor }}"

5. 使用环境保护 #

yaml 
jobs:
  deploy:
    environment: ${{ github.event.inputs.environment }}

6. 记录操作日志 #

yaml 
steps:
  - name: Log deployment
    run: |
      echo "## Deployment Log" >> $GITHUB_STEP_SUMMARY
      echo "- Environment: ${{ github.event.inputs.environment }}" >> $GITHUB_STEP_SUMMARY
      echo "- Version: ${{ github.event.inputs.version }}" >> $GITHUB_STEP_SUMMARY
      echo "- Triggered by: ${{ github.actor }}" >> $GITHUB_STEP_SUMMARY
      echo "- Time: $(date)" >> $GITHUB_STEP_SUMMARY

下一步学习 #

小结 #

  • workflow_dispatch支持手动触发工作流
  • 可以定义多种类型的输入参数
  • 通过网页、CLI或API触发
  • 使用environment保护敏感操作
  • 提供清晰的描述和默认值
  • 记录操作日志便于审计
最后更新：2026-03-28