@gebit/stax-cli

中文文档
1.12.1发布于 2026/11/09GPL-3.0-onlyES Module构建来源已验证近 30 天下载 2150

Scaffold, extend and validate projects for the stax stack framework

原始使用文档
文档目录6 节
  1. stax init
  2. stax add
  3. stax validate config
  4. folder is required
  5. Development
  6. Releasing

stax CLI

Scaffolds, extends and validates projects for the stax stack framework. Package @gebit/stax-cli, binary stax. Requires Node.js 24 or later.

npm install -g @gebit/stax-cli

stax init

Generates a deploy wrapper and an empty stack list in a repository:

FileContent
.github/workflows/deploy.ymlManual Deploy workflow calling a-wf-setup-ci.yml and a-wf-deploy-levels.yml from GEBITSolutions/stax at the installed CLI version, with matching actions-version inputs
configs/default.yamlOne commented deployment block listing every required deployment value with its GitHub variable (deployment.project live only when --project is given), stacks: [], commented examples and a yaml-language-server schema link for editor completion at the same version
stax init [directory] [--environment <github-environment>] [--project <name>] [--force] [--framework-ref <tag-or-commit-sha>]

stax init never prompts. --environment and --project are optional.

The installed CLI version sets both reusable workflow refs, both actions-version inputs and the editor schema URL. Global and project-local installs use the same rule. Use a CLI release that matches the framework version you deploy; init does not update existing configs or workflows.

--framework-ref is required only for a development build (0.0.0-development). Give it a tag, commit SHA or branch, including main if you choose to track it explicitly. Development builds do not default to main. Published CLI releases reject --framework-ref and use their own exact version.

  • --environment: default GitHub Environment preselected in the deploy form. Without it, the form has no preselection.
  • --project: lowercase letters, digits and hyphens, starting with a letter. Saved as deployment.project in configs/default.yaml; without it, the GitHub variable PROJECT supplies the value.
  • Deployment values are not asked for. The generated config lists all required ones in one block, each next to its GitHub variable. Set them at least as GitHub variables (repository or Environment); a value uncommented in the config overrides the variable.
  • Existing files are never overwritten unless --force is given. Without it, nothing is written.

Nothing is deployed until configs/default.yaml has at least one stack; add one with stax add. Set the required Azure resource, DNS and state deployment values in YAML or the matching GitHub variables before deploying; see deployment configuration.

The generated caller includes pages: write and id-token: write for GitHub Pages stacks. Existing callers upgrading to the Pages-enabled framework must add pages: write to their existing workflow permissions so nested workflow validation succeeds. A Pages-only caller can use the setup workflow's skip-azure-credentials-validation: true; see the repository's dedicated configs/stax-docs.yaml and .github/workflows/docs.yml example.

stax add

Adds a stack to a deploy config in configs/:

stax add [directory] [--config <name>] [--name <stack name>] [--type <type>] [--yes]
  • --config: configs/<name>.yaml, the name the Deploy workflow takes. Without it, the existing configs are offered. With --yes, default (or the only config) is used.
  • --name: display name. The id is derived from it: lowercase letters and digits joined by dashes, plus six random digits, e.g. Network Hub → network-hub-482913. The id is only an identifier; nothing derives paths from it.
  • --type: one of the stack types in the schema; offered as a list when missing.
  • Fields the type requires are prompted for, with the schema example as default (folder defaults to the name's slug). --yes accepts the defaults.
  • Every other field the type reads is added as a commented example with its description. Uncomment the ones you need.
  • The stack is appended after the last stack; the rest of the file stays byte for byte. A stack that would make the config invalid (e.g. a second github-pages-site-deploy stack) is not written.
  • Without a terminal, a missing value is an error.

The field list and examples come from the schema: each stack property lists the types that read it in x-stax-types ("all" for every type) and its example in examples.

stax add reads the schema bundled with the installed CLI. It works offline and does not fetch the editor schema URL in configs/default.yaml.

stax validate config

Checks deploy configs against the schema in schema/deploy-config.schema.json and against the rules the pipeline enforces.

Validation reads the schema bundled with the installed CLI, not the editor schema URL. It works offline; match your installed CLI to the framework version you deploy.

stax validate config                 # deploy configs directly in configs/
stax validate config -r              # ... and in its subdirectories
stax validate config configs/prod.yaml
stax validate config other-dir -r --strict
  • [path] is a file or a directory; it defaults to configs. A named file is always validated. When scanning a directory, YAML files without deployment, stacks, externalRepos or globals (for example Helm values) are listed as skipped.
  • Findings show line:column, severity and the field path, e.g. stacks[1].type.
  • Exit code 1 when any file has errors; warnings only fail with --strict.
  • deployment fields are optional in local validation because GitHub variables can supply them. Setup checks the required values after resolution. Unknown deployment keys fail validation because setup rejects them.
Errors (the pipeline fails or silently skips the stack)Warnings
Invalid YAML; wrong field types (e.g. local_backend: "false" instead of a boolean)Fields the schema does not know (often typos such as depend_on)
Missing id or type; unknown type; more than one github-pages-site-deploy stack or destroy on itdepends_on or stack.<id>.var.<key> pointing to a stack in another config
Type-specific required fields: folder for terraform/opentofu/function-build-deploy, Packer packer_directory/packer_version, s3-site-deploy location, script script, bizep template, function-build-deploy runtimesource_repo alias not defined in this file (configs deployed together share externalRepos)
Packer paths that are absolute, contain .., backslashes, empty segments or control characters; non-exact packer_version; build_target: hetzner without hetzner; destination fields for a different build target (also rejected by deployment setup)No stacks defined; deprecated Gallery aliases (gallery_name and the other top-level Gallery fields); build_target: aws (reserved, the workflow rejects it)
Duplicate stack ids; malformed stack.<id>.var.<key> references
Dependency cycles (including through stack.<id>... inputs); dependency chains deeper than 14 levels

folder is required

terraform, opentofu and function-build-deploy stacks must set folder: the stack directory below stack_base_path (default terraform/stacks) or below functions/. The pipeline no longer falls back to the stack id, and setup fails for a stack without folder. To migrate a stack that relied on the fallback, add folder: <its id>.

Development

cd cli
npm ci
npm run typecheck
npm test            # copies ../schema first
npm run build
npm run sync-schema && node src/cli.ts validate config ../path/to/configs   # runs from source (Node 24 type stripping)

For a development build, choose a framework ref when initializing a project, for example node src/cli.ts init ../my-project --framework-ref main (or stax init ../my-project --framework-ref main after npm link). A released CLI needs no ref and rejects this option.

Releasing

The CLI is released together with the reusable workflows, under the same version. release.yml runs on every push to main and composes the a-wf-release-* phase workflows:

  1. a-wf-release-version.yml waits for approval and derives the next version from conventional commits.
  2. cli-pack.yml sets the package version to that version, typechecks, tests, builds and packs the CLI.
  3. a-wf-release-prepare.yml commits the release changes, creates the tag and the pre-release, and attaches the packed tarball.
  4. a-wf-release-approve.yml waits for the second approval (publish-release environment).
  5. docs.yml deploys the documentation site; if it fails, nothing is published.
  6. a-wf-release-publish.yml publishes the release.
  7. cli-publish.yml runs npm publish on the same tarball.

Publishing uses npm trusted publishing (OIDC): no npm token is stored, and npm attaches a provenance attestation. The version in package.json stays 0.0.0-development; only published packages carry a real version.

版本与发布记录

@gebit/stax-cli 共发布 15 个版本,首次发布于 2026/10/20;过去 12 个月发布了 15 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.12.1latest2026/11/097 天前
1.12.02026/11/097 天前
1.11.02026/11/079 天前
1.10.02026/11/079 天前
1.9.02026/11/079 天前
1.8.02026/10/3016 天前

其他发布通道:bootstrap → 0.0.0-bootstrap.0。

关于 @gebit/stax-cli 的常见问题

@gebit/stax-cli 是什么?

Scaffold, extend and validate projects for the stax stack framework

如何安装 @gebit/stax-cli?

在项目目录运行 npm install @gebit/stax-cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 stax,可以用 npx stax 直接运行。

@gebit/stax-cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gebit__stax-cli 是否存在。

@gebit/stax-cli 支持 ESM 还是 CommonJS?

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

@gebit/stax-cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gebit/stax-cli 可以商用吗?

@gebit/stax-cli 使用 GPL-3.0-only 许可。强 Copyleft:分发包含该代码的软件时,整个作品需以 GPL-3.0 兼容许可开源,并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括,不构成法律意见,请以许可原文为准。

@gebit/stax-cli 的下载量有多少?

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

@gebit/stax-cli 还在维护吗?

最新版本 1.12.1 发布于 2026/11/09(7 天前);至今共发布 15 个版本,其中过去 12 个月发布了 15 个;首次发布于 2026/10/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。