NDDev-it-com/nddev-ci-workflows
GitHub: NDDev-it-com/nddev-ci-workflows
一套按 GitHub 仓库计费场景分层、提供 SHA 固定的可复用 CI/CD 与安全治理工作流的开源自动化知识库。
Stars: 0 | Forks: 0
# nddev-ci-workflows
一个针对 NDDev 资产的 **2026 年 7 月 GitHub 原生 CI/CD、安全、治理与供应链
自动化知识库及可复用工作流库**。
它区分了三种计费现实——**公开 OSS**、**免费私有**，以及
**付费私有/GHAS**——为每种情况提供了 SHA 固定的可复用工作流，并在 [`docs/`](docs/00-overview.md) 和机器可读的
[`catalog/`](catalog/README.md) 中记录了每项功能的状态、成本模型、风险和实现路径。
## 按仓库计费现实划分的三个层级
| 层级 | 您将获得的内容 | 备注 |
| --- | --- | --- |
| **公开 OSS** | 完整的免费安全套件：CodeQL、OSSF Scorecard、dependency review、原生 secret scanning、gitleaks、actionlint、zizmor (SARIF)、harden-runner、SBOM + attestations。 | 标准的托管 runner 和 code scanning 在公开仓库中是免费的。 |
| **免费私有** | 仅限零成本：actionlint、zizmor（无 SARIF）、gitleaks、私有静态验证、跨平台冒烟测试、SBOM + attestations、OIDC。 | CodeQL、原生 secret scanning、dependency review 和 harden-runner 在私有仓库中是 **付费的**，因此在此处被排除。 |
| **付费私有 / GHAS** | 通过 GitHub Code Security / Secret Protection，在私有仓库中包含公开仓库的所有内容。 | 需要付费计划。 |
请参阅 [`docs/01-public-oss-free.md`](docs/01-public-oss-free.md)、
[`docs/02-private-free.md`](docs/02-private-free.md) 和
[`docs/03-private-paid-ghas.md`](docs/03-private-paid-ghas.md)。
## 功能 → 工作流映射
| 功能 | 工作流 | 公开 | 免费私有 | 付费私有 |
| --- | --- | :---: | :---: | :---: |
| CodeQL code scanning | `public-codeql.yml` | ✅ | ❌ 付费 | ✅ |
| OSSF Scorecard (SARIF) | `public-scorecard.yml` | ✅ | ❌ | ✅ |
| OSSF Scorecard (JSON artifact) | `public-scorecard-json.yml` | ✅ | ❌ | ✅ |
| Dependency Review | `public-dependency-review.yml` | ✅ | ❌ 付费 | ✅ |
| Gitleaks secret scan | `secret-scan.yml` | ✅ | ✅ | ✅ |
| actionlint | `actionlint.yml` | ✅ | ✅ | ✅ |
| zizmor (SARIF) | `zizmor-sarif.yml` | ✅ | ❌（需要 code scanning） | ✅ |
| zizmor（无 SARIF） | `zizmor-no-sarif.yml` | ✅ | ✅ | ✅ |
| 跨平台冒烟测试 | `cross-platform-smoke.yml` | ✅ | ✅ | ✅ |
| 发布供应链（SBOM + attest） | `release-supply-chain.yml` | ✅ | ✅ | ✅ |
| 轻量级静态验证 | `private-static.yml` | ✅ | ✅ | ✅ |
| 语言 CI 包 | `python-ci.yml`, `node-ci.yml`, `go-ci.yml`, `rust-ci.yml`, `java-ci.yml`, `dotnet-ci.yml` | ✅ | ✅ | ✅ |
| 容器镜像扫描 (Trivy) | `container-ci.yml` | ✅ | ✅ | ✅ |
| Terraform CI | `terraform-ci.yml` | ✅ | ✅ | ✅ |
| 文档 CI | `docs-ci.yml` | ✅ | ✅ | ✅ |
| Monorepo 变更路径路由 | `monorepo-changed-paths.yml` | ✅ | ✅ | ✅ |
机器可读的事实来源是 [`catalog/capabilities.yml`](catalog/capabilities.yml)。
生成的镜像副本位于 [`docs/generated/`](docs/generated/) 中，并由 `scripts/generate_docs.py --check` 进行检查。
## 用法
始终通过 **完整的 commit SHA** 进行固定（tag 是可变的）。Dependabot 会自动更新此 SHA。
调用方作业 **必须授予可复用作业声明的所有权限**，否则运行将在启动时失败——请参阅 [`docs/04-actions-core.md`](docs/04-actions-core.md)。
### 公开仓库
安全套件（push + PR）：
```
# .github/workflows/security.yml
name: security
on:
push: { branches: [main] }
pull_request: { branches: [main] }
permissions: {}
jobs:
codeql:
permissions: { actions: read, contents: read, security-events: write }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/public-codeql.yml@
with:
languages: '["python","actions"]'
secret-scan:
permissions: { contents: read }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/secret-scan.yml@
actionlint:
permissions: { contents: read }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/actionlint.yml@
zizmor:
permissions: { contents: read, security-events: write }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/zizmor-sarif.yml@
```
Dependency Review **仅在 pull request 上运行**：
```
# .github/workflows/dependency-review.yml
name: dependency-review
on: { pull_request: { branches: [main] } }
permissions: {}
jobs:
dependency-review:
permissions: { contents: read, pull-requests: write }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/public-dependency-review.yml@
```
OSSF Scorecard **仅在 push 到默认分支 + 定时任务时运行**（该 action 不支持且不推荐在 `pull_request` 中使用），因此请将其保留在单独的文件中。当 Scorecard 应该作为检查/artifact 信号，而不是持久的 code scanning 告警来源时，请使用 `public-scorecard-json.yml`。JSON 工作流默认 `publish_results: false`，因为可复用工作流调用无法满足 OpenSSF Scorecard webapp 的发布验证格式：
```
# .github/workflows/scorecard.yml
name: scorecard
on:
push: { branches: [main] }
schedule: [{ cron: "31 2 * * 1" }]
permissions: {}
jobs:
scorecard:
permissions: { id-token: write, contents: read, actions: read }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/public-scorecard-json.yml@
```
### 私有仓库（免费最小化）
```
# .github/workflows/security.yml
name: security
on:
push: { branches: [main] }
pull_request: { branches: [main] }
permissions: {}
jobs:
secret-scan:
permissions: { contents: read }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/secret-scan.yml@
with: { enable_harden_runner: false }
actionlint:
permissions: { contents: read }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/actionlint.yml@
with: { enable_harden_runner: false }
zizmor:
permissions: { contents: read } # no security-events: write — least privilege
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/zizmor-no-sarif.yml@
validate:
permissions: { contents: read }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/private-static.yml@
with:
command: "python3 scripts/validate_all.py"
```
### 发布（任一层级）
```
# .github/workflows/release.yml
name: release
on: { push: { tags: ["[0-9]+.[0-9]+.[0-9]+"] } }
permissions: {}
jobs:
publish:
permissions: { contents: write, id-token: write, attestations: write }
uses: NDDev-it-com/nddev-ci-workflows/.github/workflows/release-supply-chain.yml@
with:
version: ${{ github.ref_name }}
package_name: my-repo
archive_paths: "README.md LICENSE VERSION CHANGELOG.md src"
```
发布是 **不可变的**，并附带 SPDX SBOM、SHA256SUMS、build-provenance attestation 以及 SBOM attestation（SLSA v1.0 Build L3）。请使用 [`scripts/verify_attestations.sh`](scripts/verify_attestations.sh) 进行验证。请参阅
[`docs/07-supply-chain-slsa-sbom-attestations.md`](docs/07-supply-chain-slsa-sbom-attestations.md)。
## 常用输入
- `runner` — runner 标签（默认为 `ubuntu-latest`）。
- `enable_harden_runner` — 双层强化开关（公开仓库为 `true`；在私有仓库中为 `false`，因为在私有仓库中 harden-runner 是付费的）。
- `upload_sarif` (zizmor) — 拆分为 `zizmor-sarif.yml`（上传）和
`zizmor-no-sarif.yml`（最小权限；无 `security-events: write`）。
- `egress_policy` — 为 harden-runner 设置 `audit`（默认）或 `block`。
每个工作流都在其头部注释中记录了完整的输入集合。
## 治理
`main` 和发布 tag 受 [`.github/rulesets/`](.github/rulesets/) 中的 **rulesets** 保护（签名 commit、必需的审查 + code-owner 审查、线性历史、`ci-gate` 状态检查、tag 保护）。请参阅 [`docs/08-governance-rulesets.md`](docs/08-governance-rulesets.md) 了解 rulesets 优先模型以及从经典分支保护迁移的指南。
## 仓库映射
```
docs/ CI/CD encyclopedia (public/private tiers, security, supply chain, governance, AI)
catalog/ machine-readable capability + tools + deprecations catalog
docs/generated/ catalog-derived matrices (do not edit by hand)
.github/
workflows/ reusable workflows (the product)
rulesets/ branch/tag/push ruleset specs
ISSUE_TEMPLATE/ issue forms
scripts/ static validators (validate_all.py) + attestation verifier
examples/ copy-paste caller workflows per tier
```
## 约定
- 第三方 action 使用完整的 commit SHA 固定，并附带版本注释。
- 到处都使用最小权限的 `permissions`、`concurrency` 和 `timeout-minutes`。
- 在 `run:` 中不内联使用 `${{ inputs.* }}`（通过 `env:` 传递——zizmor 模板注入强化）。
- Digest 固定的容器镜像（gitleaks）和校验和验证的下载（actionlint）。
## 许可证
[AGPL-3.0-or-later](LICENSE)。作者：Danil Silantyev (github:rldyourmnd)，NDDev 首席执行官。
- 安全策略：[SECURITY.md](SECURITY.md)
- 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)
- 发布版本：https://github.com/NDDev-it-com/nddev-ci-workflows/releases
标签：AI应用开发, DevSecOps, GitHub Actions, 上游代理, 代码安全, 漏洞枚举, 自动笔记, 逆向工具