GitHub-Script 完全指南：在 GitHub Actions 中轻松编写 API 脚本

GitHub-Script 是 GitHub 官方提供的一个强大工具，让开发者能够在 GitHub Actions 工作流中使用 JavaScript 轻松编写和执行 GitHub API 脚本。无论你是想要自动化代码审查、管理 issues、还是实现复杂的 CI/CD 流程，这个工具都能帮你快速实现。

🚀 什么是 GitHub-Script？

GitHub-Script 是一个 GitHub Action，它让你可以直接在工作流中编写 JavaScript 脚本来调用 GitHub API。通过这个工具，你可以：

• 📝 自动评论和标记 issues
• 🔄 管理 pull requests 流程
• 📊 获取仓库统计信息
• 🎯 实现自定义自动化逻辑

✨ 核心功能特性

预配置的 API 客户端

GitHub-Script 提供了一个预先认证的 github 客户端，基于 octokit/rest.js 构建，支持分页功能，让你无需担心认证细节就能直接调用 GitHub API。

完整的上下文信息

你可以访问丰富的 context 对象，包含工作流运行的完整上下文信息，如仓库信息、触发事件详情等。

🛠️ 快速开始使用

基础配置

在你的 GitHub Actions 工作流中添加以下步骤：

- name: Run GitHub Script
  uses: actions/github-script@v7
  with:
    script: |
      console.log('Hello from GitHub Script!')
      console.log(`当前仓库：${context.repo.owner}/${context.repo.repo}`)

实际应用场景

自动评论新 issues

当有人创建新的 issue 时，自动发送欢迎评论：

on:
  issues:
    types: [opened]

jobs:
  welcome-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: '👋 感谢提交问题！我们会尽快处理。'
            })

🔧 高级功能详解

结果编码配置

GitHub-Script 支持两种结果编码方式：

• JSON 编码（默认）：适合复杂数据结构
• 字符串编码：适合简单的文本输出

- uses: actions/github-script@v7
  id: my-script
  with:
    result-encoding: string
    script: return "这个结果将以字符串形式输出"

重试机制

在网络不稳定的情况下，你可以配置自动重试：

- uses: actions/github-script@v7
  with:
    retries: 3
    script: |
      // 如果请求失败，最多重试3次
      github.rest.issues.get({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
      })

📁 项目结构概览

GitHub-Script 项目采用 TypeScript 开发，主要文件包括：

• action.yml - Action 的配置文件
• src/main.ts - 主入口文件
• src/async-function.ts - 异步函数处理逻辑
• types/async-function.d.ts - TypeScript 类型定义

🎯 最佳实践建议

1. 使用外部脚本文件

对于复杂的脚本逻辑，建议使用外部文件：

steps:
  - uses: actions/checkout@v3
  - uses: actions/github-script@v7
    with:
      script: |
        const myScript = require('./scripts/my-automation.js')
        await myScript({github, context, core})

2. 环境变量管理

通过环境变量传递配置信息：

steps:
  - uses: actions/github-script@v7
    env:
      CONFIG_VALUE: 'some-setting'
    with:
      script: |
        const config = process.env.CONFIG_VALUE
        console.log(`使用配置：${config}`)

💡 实用技巧

处理 GraphQL 查询

GitHub-Script 支持执行自定义 GraphQL 查询：

steps:
  - uses: actions/github-script@v7
    with:
      script: |
        const query = `
          query($owner:String!, $name:String!) {
            repository(owner:$owner, name:$name) {
              name
              description
            }
          }`
        const result = await github.graphql(query, {
          owner: context.repo.owner,
          name: context.repo.repo
        })
        console.log(result)

🔄 版本迁移指南

从 V6 升级到 V7 版本时需要注意：

• 运行时环境从 Node 16 升级到 Node 20
• 可能受到 Node 版本差异的影响

🎉 总结

GitHub-Script 为 GitHub Actions 工作流提供了强大的脚本执行能力，让开发者能够轻松实现各种自动化场景。无论是简单的通知任务还是复杂的业务流程，这个工具都能帮你高效完成。

通过本指南，你已经掌握了 GitHub-Script 的核心概念和使用方法。现在就开始在你的项目中尝试使用这个强大的工具吧！🚀