Just-Silver GitHub / Gitea Actions 工作流编写
Overview
GitHub Actions 与 Gitea Actions 约 95% 语法通用（后者兼容前者）。禁止凭记忆臆造语法——所有键、事件、表达式、上下文以官方文档为准，references/ 已提炼要点，按需加载。
When to Use
- 新建/修改
.github/workflows/*.yml或.gitea/workflows/*.yml - 选触发事件、写
if/${{ }}/ matrix、配permissions/concurrency - 不确定
github.*/secrets/needs/matrix可用性 - 排查 workflow 语法或 CI 失败
不适用：GitLab CI / Jenkins 等其他 CI。
前置路由（按需加载，不全读）
| 场景 | 读取 |
|---|---|
顶层键、on、jobs、steps、permissions、matrix/outputs |
references/workflow-syntax.md |
触发事件与 pull_request_target 安全 |
references/events.md |
${{ }}、运算符、函数、状态检查 |
references/expressions.md |
github / secrets / needs 等上下文 |
references/contexts.md |
| Gitea 目标必读：目录、token、权限、版本差异 | references/gitea-differences.md |
| 质量门禁、CI 优化、部署策略 | references/ci-cd-practices.md |
CD/发版/Release（含 push.tags / releases API / cd.yml） |
references/ci-cd-practices.md + references/changelog-conventions.md 必读（CHANGELOG 是输入，Release 引用它；单一版本源仓 tag==CHANGELOG==包版本 一致性进流水线；monorepo/多制品仓先识别各自版本源，不强行统一——见 shipping-and-launch） |
凡文件含
push.tags、releasesAPI、CHANGELOG或任务含“发版/CD/Release”，必须走此分支；绕过即违规，gitea-differences.md的git log演示不得覆盖本分支。
先确认平台：GitHub → 1-4；Gitea → 1-4 +
gitea-differences.md必读（版本未知默认按 1.27 保守编写；版本已知或语法存疑时以对应版本官方文档为准，本文件只是速查）。
校验
scripts/actionlint.exe（Windows amd64, v1.7.12）支持单/多文件与 stdin：scripts/actionlint.exe .github/workflows/ci.yml；Gitea 须显式路径。pwsh 下 *.yml 不自动展开，逐个列出。误报 gitea 用 -ignore 'undefined variable "gitea"'。版本源 scripts/actionlint.version，先跑 scripts/update-actionlint.ps1 单次保鲜。
Common Mistakes
- 凭记忆写
on/permissions→ 必读对应 reference - Gitea 套用
environment/{group:,labels:}/ 专属 scope /GITHUB_TOKEN - 目标 Gitea 为 1.27（仅
always()）却用标准函数 → 用事件过滤与==替代（1.28+ 目标才可用函数） secrets误用于if、pull_request_target滥用、tag 回推忘HEAD:main- 硬编码
http://server:3500/ 固定owner/repo→ 用${{ github.server_url }}/${{ github.repository }}/${{ github.ref_name }}动态拼接（gitea-differences.mdRelease/回推通用模板，push 需去协议头） - 发版流水线未校验
tag == CHANGELOG == package.json（单一版本源仓；monorepo/多制品按各自版本源）或 Release body 非来自CHANGELOG.md（见changelog-conventions.md一致性卡点）→ CD 发版必须从CHANGELOG.md该版本小节提取 body，git log堆砌属违规 - 带
git push回推的 workflow 用cancel-in-progress: true或各用不同group名 → 取消丢提交 / 照样 push 冲突；须多个 workflow 共用同一group名 +cancel-in-progress: false排队（见ci-cd-practices.md「多 workflow 回推排队」）
发版（CD）落地清单
写完/检查含 push.tags / releases / cd.yml 的 workflow 后逐项过：
-
CHANGELOG.md存在且顶部有## [Unreleased]，发版前已整理为## [x.y.z] - YYYY-MM-DD（见references/changelog-conventions.md） - CD 含
tag == CHANGELOG == package.json一致性校验（单一版本源仓），不一致即 fail - Release body 来自
CHANGELOG.md该版本小节截段，非git log堆砌（模板见references/gitea-differences.md「Gitea Release 发布」）