手动触发GitHub Actions工作流部署指南

在日常开发中，我们通常通过推送代码或创建标签来自动触发GitHub Actions工作流。但有时我们需要手动触发特定分支的工作流，例如当我们想要部署一个已经合并但还没有打标签的分支时。本文介绍了一个自定义脚本，用于手动触发GitHub Actions工作流，让部署工作更加灵活高效。

📋 功能特点 #

✅ 支持选择前端或后端部署工作流
✅ 自动使用当前Git分支，无需手动指定
✅ 显示GitHub Actions链接，方便实时查看部署状态
✅ 提供友好的命令行交互界面
✅ 支持通过参数自定义多种部署选项
✅ 集成BitWarden密钥管理（可选）

🔧 前提条件 #

在使用此脚本前，请确保你的环境满足以下条件：

已安装Git命令行工具
已安装curl（用于API请求）和jq（用于JSON处理）
已有GitHub个人访问令牌(PAT)，具有仓库workflow权限
如果使用BitWarden管理密钥，需要有BitWarden CLI并已登录

🔑 创建GitHub Personal Access Token #

要使用此脚本，你需要创建一个GitHub个人访问令牌：

创建步骤如下：

打开 GitHub 官网，登录你的账号
点击右上角头像 → Settings
左侧菜单点击 Developer settings
点击 Personal access tokens → 选择：
- Tokens (classic)：经典方式（适合快速测试）
- Fine-grained tokens：更安全，权限更细化（推荐）
点击 Generate new token
设置：
- 名称：描述性名称，如"Workflow Deployment"
- 有效期：根据需要设置（建议30-90天）
- 权限：确保勾选 workflow 和 repo 权限
点击生成后，立即复制并保存token（仅显示一次）

获取到Token后，有以下几种配置方式：

直接修改脚本中的 GITHUB_TOKEN 变量（不推荐，存在安全风险）
设置为环境变量：export GITHUB_TOKEN=your_token_here
使用BitWarden等密码管理工具，按照脚本中的方式配置（最安全）

🚀 使用方法 #

基本用法 #

最简单的使用方式是直接运行脚本：

./bin/deploy-github-action.sh

运行后，脚本会显示交互式界面，让你选择要部署的工作流：

请选择要部署的工作流:
1) 前端部署 (frontend_deploy.yml)
2) 后端部署 (backend_deploy.yml)
请输入选项 [1/2]:

高级用法 #

你也可以通过命令行参数直接指定部署选项，跳过交互界面：

./bin/deploy-github-action.sh --branch=feature/new-feature --workflow=frontend_deploy.yml

支持的参数包括：

--branch=<分支名>: 指定要部署的分支（默认为当前分支）
--workflow=<工作流名>: 指定要触发的工作流文件名
--owner=<用户名>: 指定GitHub仓库所有者（默认为配置的所有者）
--repo=<仓库名>: 指定GitHub仓库名称（默认为配置的仓库名）
--token=<令牌>: 可选参数，直接指定GitHub令牌（不推荐）

📜 完整脚本代码 #

以下是完整的脚本代码，将其保存为 bin/deploy-github-action.sh 并添加执行权限：

#!/bin/bash

# 用于手动触发 GitHub Actions 工作流
# 使用方法: ./bin/deploy-github-action.sh [--branch=分支名] [--workflow=工作流名] [--owner=用户名] [--repo=仓库名]

BW_CONFIG_ITEM_ID=c9bc1ea3-8dd7-4b04-b56a-ae01cb223261
BW_SECRETS=$(bw get item "$BW_CONFIG_ITEM_ID" | jq -r '.fields[] | "\(.name)=\(.value)"')
# Export secrets as environment variables
GITHUB_TOKEN=$(echo "$BW_SECRETS" | grep "^GITHUB_TOKEN=" | cut -d'=' -f2)

# 获取当前Git分支
CURRENT_BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "main")

# 默认值设置
BRANCH="$CURRENT_BRANCH"
WORKFLOW=""
WORKFLOW_BACKEND="backend_deploy.yml"
WORKFLOW_FRONTEND="frontend_deploy.yml"
OWNER=${GITHUB_OWNER:-"GraysonChen"}
REPO=${GITHUB_REPO:-"pomodoro-tracker"}

# 解析命名参数
for i in "$@"
do
case $i in
    --branch=*)
    BRANCH="${i#*=}"
    shift
    ;;
    --workflow=*)
    WORKFLOW="${i#*=}"
    shift
    ;;
    --owner=*)
    OWNER="${i#*=}"
    shift
    ;;
    --repo=*)
    REPO="${i#*=}"
    shift
    ;;
    --token=*)
    TOKEN="${i#*=}"
    shift
    ;;
    *)
    # 未知选项
    ;;
esac
done

# 如果没有指定工作流，则显示交互式选择界面
if [ -z "$WORKFLOW" ]; then
    echo "请选择要部署的工作流:"
    echo "1) 前端部署 (${WORKFLOW_FRONTEND})"
    echo "2) 后端部署 (${WORKFLOW_BACKEND})"
    read -p "请输入选项 [1/2]: " choice
    
    case $choice in
        1)
            WORKFLOW=$WORKFLOW_FRONTEND
            echo "已选择前端部署工作流"
            ;;
        2)
            WORKFLOW=$WORKFLOW_BACKEND
            echo "已选择后端部署工作流"
            ;;
        *)
            echo "无效选项，默认选择前端部署工作流"
            WORKFLOW=$WORKFLOW_FRONTEND
            ;;
    esac
fi

# 发送API请求触发工作流
response=$(curl -s -X POST \
  -H "Authorization: token ${GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github.v3+json" \
  "https://api.github.com/repos/${OWNER}/${REPO}/actions/workflows/${WORKFLOW}/dispatches" \
  -d "{\"ref\": \"${BRANCH}\"}" \
  -w "\n%{http_code}")

# 获取响应内容和状态码
http_body=$(echo "$response" | sed '$d')
http_code=$(echo "$response" | tail -n1)

echo "已请求部署 ${OWNER}/${REPO} 仓库的 ${BRANCH} 分支，使用工作流: ${WORKFLOW}"

# 检查响应状态
if [ "$http_code" = "204" ]; then
    # 构建GitHub Actions URL
    ACTIONS_URL="https://github.com/${OWNER}/${REPO}/actions"
    echo "✅ 触发成功!"
    echo "🔗 GitHub Actions 链接: ${ACTIONS_URL}"
else
    echo "❌ 触发失败，HTTP状态码: ${http_code}"
    echo "错误信息: ${http_body}"
fi

确保给脚本添加执行权限：

chmod +x bin/deploy-github-action.sh

⚙️ 工作原理 #

此脚本利用GitHub API的workflow_dispatch触发器来手动启动工作流。具体步骤如下：

获取环境信息：自动获取当前Git分支（如果未指定分支）
获取认证信息：从BitWarden或环境变量获取GitHub令牌
交互选择：如果未通过参数指定，提供交互式界面选择工作流
发起API请求：发送HTTP POST请求到GitHub API触发指定的工作流
处理响应：分析响应状态码，显示部署状态和GitHub Actions链接

⚠️ 注意事项 #

使用此脚本时，请注意以下几点：

确保工作流文件(.github/workflows/xxx.yml)中已配置workflow_dispatch触发器
GitHub令牌需要有足够的权限来触发工作流
部署前确认分支名称正确，避免部署错误的代码
定期更新GitHub令牌，确保安全性
建议将敏感信息存储在密码管理工具中

📝 配置工作流文件 #

为了使脚本能够正常工作，需要在工作流文件中添加workflow_dispatch触发器，例如：

name: Deploy
on:
  workflow_dispatch:
    inputs:
      deploy_env:
        description: '部署环境'
        required: false
        default: 'production'
        type: choice
        options:
          - production
          - staging
  push:
    tags:
      - "v*.*.*"

这样配置后，工作流既可以通过推送标签自动触发，也可以通过此脚本手动触发。

🔍 故障排除 #

如果触发失败，可能有以下几种常见原因：

认证问题：GitHub令牌过期或权限不足
配置问题：工作流文件未配置workflow_dispatch触发器
分支问题：指定的分支名称不存在
格式问题：API请求格式不正确或参数有误
网络问题：无法连接到GitHub API服务器

遇到问题时，请检查脚本输出的错误信息，根据提示修复问题后重试。

📊 使用场景 #

此脚本特别适合以下场景：

需要频繁部署测试环境但不想每次都创建标签
多人协作开发，需要灵活部署不同分支
CI/CD流程需要手动触发步骤
紧急修复需要快速部署到特定环境

💡 总结 #

这个脚本提供了一种便捷的方式来手动触发GitHub Actions工作流，让部署过程更加灵活高效。通过简单的命令行操作，你可以快速部署任意分支到指定环境，大大提高开发和部署效率。它特别适合需要频繁部署但不想每次都创建标签的开发场景，是DevOps工具箱中的实用工具。