枪

这个 gat 项目是用于 使用 TypeScript 写入您的 GitHub 动作工作流程。 。 。 .

维护 YAML 文件很困难, 如果你的项目足够大的话, 你会发现自己在工作流程之间复制了很多代码 。 与 gat 您可以仅仅使用 TypeScript 对象创建可重复使用的工作和步骤,并在工作流程模板中导入它们.

为什么 gat? 吗? 名字是"GitHub Actions Template Generator"的缩写,没有最后一部分,因为 gat 加泰罗尼亚语中"猫"的意思.

安装

使用以下命令安装主软件包及其依赖性:

npm i -D @factorialco/gat typescript tsx commander @swc/core

使用量

写入模板

这个 gat CLI假设你有 index.ts 内部文件 .github/templates。让我们创建第一个模板:

// .github/templates/index.ts
import { Workflow } from "@factorialco/gat";

await new Workflow("My first workflow")
  .on("push")
  .addJob("test", {
    steps: [
      {
        uses: "actions/checkout@v3",
      },
      {
        uses: "actions/setup-node@v3",
      },
      {
        run: "npm test",
      },
    ],
  })
  .compile({ filePath: "my-first-workflow.yml" });

请注意,你需要呼叫 compile() 方法,将选项对象与 filePath 用于创建 GitHub 动作工作流程.

编译您的模板

您可以在根文件夹中构建运行此命令的模板 :

npx gat build

遵循前一个例子, 您现在应该看到一个文件 .github/workflows/my-first-workflow.yml 像这样:

# Workflow automatically generated by gat
# DO NOT CHANGE THIS FILE MANUALLY

name: My first workflow
on:
  push: null
jobs:
  test:
    runs-on: ubuntu-22.04
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm test

注意到该工作包括一些假设,如: runs-on 财务报告和审定财务报表 timeout-minutes 字段。 你可以在增加新工作时改变这些.

正在编译许多模板

compileTemplates 在一个调用中将输出文件名映射到工作流程 :

// .github/templates/index.ts
import { compileTemplates } from "@factorialco/gat";

import Build from "./build";
import Deploy from "./deploy";

compileTemplates({
  templates: {
    "build.yml": Build,
    "deploy.yml": Deploy,
  },
});

它接受这些选项:

writeLockFile 财务报告和审定财务报表 failOnUnlockedActions 需要一个 lockFilePath。 。 。 .

固定动作

标签, 如 actions/checkout@v4 可以转移到不同的承诺。 为了保证一个工作流程总是运行你审查过的代码,将每个动作都钉入一个承诺. 你可以用两种方式做到这一点。 使用其中一个,而不是两个.

选项 A: gat 锁定文件

gat 写入工作流程时,将每个动作标记替换为承诺 SHA .

1. 添加 lockFilePath 财务报告和审定财务报表 writeLockFile 改为 compileTemplates,并读 writeLockFile 从环境变量:

   compileTemplates({
     templates,
     lockFilePath: ".github/templates/gat-lock.json",
     writeLockFile: process.env.GAT_WRITE_LOCK_FILE === "true",
     failOnUnlockedActions: true,
   });
   

2. 运行建设一次 GAT_WRITE_LOCK_FILE=true (单位:千美元) GITHUB_TOKENGat 使用 GitHub API 解决每个标签并写入 gat-lock.json数字 :

   {
     "actions/[email protected]": "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683"
   }
   

3. 提交锁定文件 。 以后再写再读 uses: actions/checkout@11bd719... 输入工作流程.

与 failOnUnlockedActions: true,当一个步骤使用一个没有条目的动作时,构建停止。 没有它,Gat会写出标记,那步没有被钉住. SHA refs,当地 ./ 行动 docker:// 未检查图像 .

锁文件有这些限制 :

• 写会解决模板使用的每一个动作并重写整个文件. 它可以将其它动作移动到新的承诺并删除您手工添加的条目. 全面审查 gat-lock.json。 。 。 .
• 只有台阶被钉住。 行动要求的行动(过渡性依赖性)和可重复使用的工作流程没有固定.

选项B: GitHub 工作流程锁定文件

GitHub 可以用 工作流程依赖锁定文件编辑 gh actions-lock 扩展写 .github/workflows/actions.lock,则GitHub Actions运行锁定的输入。 它还标出过渡性依赖性,并检查动作存储器没有改变所有者.

1. 未设置 lockFilePath. gat 然后从模板中写入标签.

2. 安装扩展名 : gh extension install github/gh-actions-lock。 。 。 .

3. 每次构建后, 从寄存器根更新锁定文件 :

   npx gat build
   gh actions-lock --no-narrow
   

   总是使用 --no-narrow没有它,工具会重写 uses: 例如工作流程中的行 @v4 改为 @v4.2.2。然后,工作流程将不再匹配模板,下一个构建将取消更改.

4. 提交 actions.lock 与工作流程。 不要用手编辑它.

5. 在CI中,检查每个拉出请求中更改工作流程的锁文件. 绑定扩展版本 :

   - run: gh extension install github/gh-actions-lock --pin v0.2.0
     env:
       GH_TOKEN: ${{ github.token }}
   - run: gh actions-lock --verify
     env:
       GH_TOKEN: ${{ github.token }}
   

   --verify 当一个工作流程或一个动作没有条目时失败,当一个锁定的承诺不再有效时失败.

GitHub锁文件在公开预览中,其格式可以改变. 如果锁文件无效,GitHub会忽略并运行标记,所以CI检查很重要.

不合并选项

两种选项都包含工作流程包含SHA. gh actions-lock 警告每个SHA参考。 无 --no-narrow,它也会将SHA重写为标记. 为寄存器选择一个选项 .

创建自己的工作流程类

您可以创建返回预配置的工厂功能 Workflow 有共享设置的示例。 这样可以避免模板的重复:

// .github/templates/helpers.ts
import { Workflow } from "@factorialco/gat";

export function createWorkflow(name: string) {
  return new Workflow(name)
    .setEnv("NODE_ENV", "production")
    .on("push", { branches: ["main"] });
}

然后用在您的模板中 :

// .github/templates/index.ts
import { createWorkflow } from "./helpers";

await createWorkflow("Test")
  .addJob("test", {
    steps: [{ run: "npm test" }],
  })
  .compile({ filePath: "test.yml" });

await createWorkflow("Lint")
  .addJob("lint", {
    steps: [{ run: "npm run lint" }],
  })
  .compile({ filePath: "lint.yml" });

这样,您的所有工作流程都共享相同的环境变量,触发,以及您在工厂函数中配置的任何其他默认值.

捐款

1. 将寄存器分叉并克隆到本地
2. 安装依赖性 : npm install
3. 运行测试 : npm test
4. 做修改,确保考试合格
5. 提交拉动请求

许可证

麻省理工学院