gh-actions-build-trigger

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GH Actions build trigger

GH Actions 构建触发

When a repo has several workflows (e.g. an APK workflow and an AAB workflow), they do not behave the same. Know each one's auto-trigger and paths filter before pushing:

Workflow	Auto-trigger on push	Paths filter
`build-apk.yml` (test APK)	✅ every push to `main`	often none
`build-aab.yml` (store AAB)	✅ push to `main`	often only app source paths (app/, components/, db/, hooks/, lib/, plugins/, types/, assets/, app.json, package.json, patches/) — NOT `.github/*`

Check the actual

paths:

paths-ignore:

in each workflow file — don't assume.

当仓库拥有多个工作流（例如APK工作流和AAB工作流）时，它们的行为并不一致。推送代码前，请了解每个工作流的自动触发规则和路径过滤设置：

工作流	推送至main时自动触发	路径过滤
`build-apk.yml` （测试APK）	✅ 每次推送至 `main` 分支	通常无过滤
`build-aab.yml` （应用商店AAB）	✅ 推送至 `main` 分支	通常仅包含应用源码路径（app/, components/, db/, hooks/, lib/, plugins/, types/, assets/, app.json, package.json, patches/）——不包含 `.github/*`

请查看每个工作流文件中的实际

paths:

paths-ignore:

配置，不要凭假设判断。

Steps

操作步骤

1. Decide which workflow(s) the request needs

1. 确定需求对应的工作流

APK for sideloading/testing, AAB for Play Store. If the user asks for one, cancel the other — pushing to

main

may trigger both (the no-filter workflow always runs). Never let a build the user did not ask for burn runner time.

APK用于侧载/测试，AAB用于Google Play商店。如果用户只需要其中一种，取消另一种——推送至

main

分支可能会同时触发两个工作流（无路径过滤的工作流总会运行）。不要让用户不需要的构建占用运行器资源。

2. Check whether a push will trigger the workflow

2. 检查推送是否会触发工作流

A push that touches only
.github/**
(workflow files, etc.) does NOT trigger a workflow whose paths filter omits

.github/**

. Pushing a workflow-file-only commit will still trigger a workflow with no filter. For the filtered workflow in that case, use a manual dispatch (step 3) instead of expecting the push to fire it.

如果推送仅修改了**

.github/**

目录（如工作流文件等），那么路径过滤中排除
.github/**
的工作流不会被触发**。仅修改工作流文件的提交仍会触发无路径过滤的工作流。对于有路径过滤的工作流，这种情况下需要使用手动调度（步骤3），而不是等待推送触发。

3. Trigger (manual dispatch when needed)

3. 触发工作流（必要时手动调度）

bash

curl -s -o /dev/null -w "dispatch: HTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/workflows/<workflow-file>.yml/dispatches" \
  -d '{"ref":"main"}'

= accepted. After dispatch (or a push), runs can take several seconds to appear in the API — the first query right after a push may return an empty list. Sleep ~5–10s and re-query before concluding "nothing triggered" (a classic race).

bash

curl -s -o /dev/null -w "dispatch: HTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/workflows/<workflow-file>.yml/dispatches" \
  -d '{"ref":"main"}'

表示请求已接受。调度（或推送）后，运行任务可能需要几秒才会出现在API中——推送后立即查询可能返回空列表。请等待约5-10秒后重新查询，再判断“未触发任何任务”（这是典型的竞态条件问题）。

4. Monitor the run

4. 监控运行状态

bash

curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/runs?per_page=5" \
  | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8')); for (const r of d.workflow_runs||[]) console.log(r.id, r.name, r.head_sha.slice(0,7), r.status, r.conclusion, r.event)"

conclusion: null

while running. If a run fails, pull the job log:

bash

JOB_ID=$(curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/runs/$RUN_ID/jobs" \
  | node -e "console.log(JSON.parse(require('fs').readFileSync(0,'utf8')).jobs[0].id)")
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/<owner>/<repo>/actions/jobs/$JOB_ID/logs" -o /tmp/job.log

Then grep the log for the failing step (e.g.

grep -B2 -A12 "error"

or look for

##[error]

Process completed with exit code 1

bash

curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/runs?per_page=5" \
  | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8')); for (const r of d.workflow_runs||[]) console.log(r.id, r.name, r.head_sha.slice(0,7), r.status, r.conclusion, r.event)"

运行中时

conclusion

的值为

null

。如果运行失败，拉取作业日志：

bash

JOB_ID=$(curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/runs/$RUN_ID/jobs" \
  | node -e "console.log(JSON.parse(require('fs').readFileSync(0,'utf8')).jobs[0].id)")
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/<owner>/<repo>/actions/jobs/$JOB_ID/logs" -o /tmp/job.log

然后在日志中搜索失败步骤（例如使用

grep -B2 -A12 "error"

，或查找

##[error]

Process completed with exit code 1

）。

5. Cancel an unneeded parallel run

5. 取消不需要的并行运行任务

bash

curl -s -o /dev/null -w "cancel: HTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/runs/$RUN_ID/cancel"

= accepted. Note: cancelling is async — the run may show as "cancelled" only after the runner notices.

Completion criterion: the correct workflow(s) for the request are running on the intended commit, unneeded parallel runs are cancelled, and you know the run ID + URL to report. If a build failed, you can name the failing step and the error.

bash

curl -s -o /dev/null -w "cancel: HTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/actions/runs/$RUN_ID/cancel"

表示请求已接受。注意：取消操作是异步的——运行任务可能要等运行器检测到后才会显示为“已取消”。

完成标准：需求对应的工作流在指定提交上运行，不需要的并行任务已取消，并且你已获取运行ID和报告链接。如果构建失败，你能指出失败步骤和错误信息。

Reference

参考信息

Token: a
```
gh_token
```
is provided per session; export it as
```
GH_TOKEN
```
and never write it into files/commits.
Artifacts are uploaded by
```
actions/upload-artifact@v4
```
; the artifact name and path are declared in the workflow's upload step.
First build on a fresh runner takes ~15–25 min; cached ones are faster.

令牌：每个会话会提供
```
gh_token
```
；请将其导出为
```
GH_TOKEN
```
，切勿写入文件或提交中。
产物由
```
actions/upload-artifact@v4
```
上传；产物名称和路径在工作流的上传步骤中声明。
全新运行器上的首次构建需约15-25分钟；使用缓存的构建速度更快。