# @factorialco/gat 中文文档

规范地址：https://npmcn.com/package/%40factorialco/gat/

版本：3\.13\.0
npm 元数据更新时间：2026-10-16T08:27:10.224Z
中文译文更新时间：2026-11-14T08:28:37.779Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40factorialco/gat
原文对照：https://npmcn.com/package/%40factorialco/gat/?lang=original
项目主页：https://github.com/factorialco/gat#readme
源码仓库：https://github.com/factorialco/gat

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：47.2 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2022-08-26T12:46:03.111Z
- 最新版本发布：2026-10-16T08:27:09.406Z
- 近 30 天下载量：18537（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 5 个）

## 中文简介

使用 TypeScript 写入您的 GitHub 动作工作流程

## 安装

```sh
npm install @factorialco/gat
```

也可以使用：`pnpm add @factorialco/gat`、`yarn add @factorialco/gat`、`bun add @factorialco/gat`

## README

![](https://npmcn.com/package/%40factorialco/gat/gat.png)

# 枪 ![Build](https://github.com/factorialco/gat/actions/workflows/build.yml/badge.svg?branch=main) [![npm version](https://badge.fury.io/js/@factorialco%2Fgat.svg)](https://badge.fury.io/js/@factorialco%2Fgat)

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

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

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

## 安装

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

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

## 使用量

### 写入模板

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

```ts
// .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 动作工作流程.

### 编译您的模板

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

```bash
npx gat build
```

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

```yaml
# 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` 在一个调用中将输出文件名映射到工作流程 :

```ts
// .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,
  },
});
```

它接受这些选项:

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `templates` |  | 文件名地图 `.github/workflows` 改为 `Workflow` 实例. |
| `lockFilePath` | 无 | 路径 a `gat-lock.json` 文档。 没有它, Gat 写回信没有改变. |
| `writeLockFile` | `false` | 解析每个动作标记到一个承诺的 SHA 并重写锁文件 . |
| `failOnUnlockedActions` | `false` | 当一个步骤使用锁文件中没有条目的动作时停止 . |

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

### 固定动作

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

#### 选项 A: gat 锁定文件

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

1.  添加 `lockFilePath` 财务报告和审定财务报表 `writeLockFile` 改为 `compileTemplates`,并读 `writeLockFile` 从环境变量:
    
    ```ts
    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_TOKEN`Gat 使用 GitHub API 解决每个标签并写入 `gat-lock.json`数字 :
    
    ```json
    {
      "actions/checkout@v4.2.2": "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683"
    }
    ```
    
3.  提交锁定文件 。 以后再写再读 `uses: actions/checkout@11bd719...` 输入工作流程.
    

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

锁文件有这些限制 :

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

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

GitHub 可以用 [工作流程依赖锁定文件](https://docs.github.com/en/actions/concepts/security/workflow-dependency-lockfiles)编辑 [`gh actions-lock`](https://github.com/github/gh-actions-lock) 扩展写 `.github/workflows/actions.lock`,则GitHub Actions运行锁定的输入。 它还标出过渡性依赖性,并检查动作存储器没有改变所有者.

1.  未设置 `lockFilePath`. gat 然后从模板中写入标签.
    
2.  安装扩展名 : `gh extension install github/gh-actions-lock`。 。 。 .
    
3.  每次构建后, 从寄存器根更新锁定文件 :
    
    ```bash
    npx gat build
    gh actions-lock --no-narrow
    ```
    
    总是使用 `--no-narrow`没有它,工具会重写 `uses:` 例如工作流程中的行 `@v4` 改为 `@v4.2.2`。然后,工作流程将不再匹配模板,下一个构建将取消更改.
    
4.  提交 `actions.lock` 与工作流程。 不要用手编辑它.
    
5.  在CI中,检查每个拉出请求中更改工作流程的锁文件. 绑定扩展版本 :
    
    ```yaml
    - 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` 有共享设置的示例。 这样可以避免模板的重复:

```ts
// .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"] });
}
```

然后用在您的模板中 :

```ts
// .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.  提交拉动请求

## 许可证

麻省理工学院

## 常见问题

### @factorialco/gat 是什么？

使用 TypeScript 写入您的 GitHub 动作工作流程

### 如何安装 @factorialco/gat？

在项目目录运行 npm install @factorialco/gat，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gat，可以用 npx gat 直接运行。

### @factorialco/gat 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @factorialco/gat 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @factorialco/gat 可以商用吗？

@factorialco/gat 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @factorialco/gat 的下载量有多少？

根据 npm 官方下载统计，@factorialco/gat 在 2026/10/14 – 2026/11/12 这 30 天内被下载 18,537 次，日均约 618 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @factorialco/gat 还在维护吗？

最新版本 3\.13\.0 发布于 2026/10/16（29 天前）；至今共发布 60 个版本，其中过去 12 个月发布了 5 个；首次发布于 2022/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。