Skip to content

Commit ec1e5ac

Browse files
Hongwei-MBHongwei-MB
committed
Add README and sync docs with restructured 4-job pipeline
- Add engaging README with badges, pipeline diagram, and quick start - Update quick-start-release.md for merged release job - Update github-workflows-guide.md for 4-job structure and installer-only releases Made-with: Cursor
1 parent 0fbf66e commit ec1e5ac

3 files changed

Lines changed: 172 additions & 24 deletions

File tree

‎README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# dotnet.CI.template
2+
3+
[![CI and Release](https://github.com/AGIBuild/dotnet.CI.template/actions/workflows/ci.yml/badge.svg)](https://github.com/AGIBuild/dotnet.CI.template/actions/workflows/ci.yml)
4+
[![CodeQL](https://github.com/AGIBuild/dotnet.CI.template/actions/workflows/codeql.yml/badge.svg)](https://github.com/AGIBuild/dotnet.CI.template/actions/workflows/codeql.yml)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6+
7+
**Stop wiring CI from scratch.** Start with a production-grade pipeline that builds, tests, packages, and releases your .NET projects across platforms -- with a single approval click.
8+
9+
---
10+
11+
## What You Get
12+
13+
Use this template and you instantly have:
14+
15+
```
16+
Push to main
17+
|
18+
v
19+
resolve-version ── Reads VersionPrefix, computes matrix, outputs version info
20+
|
21+
v
22+
build-and-test ─── Matrix build (linux / windows / macos)
23+
| + Pack NuGet + Publish + Package installers
24+
|
25+
v
26+
release ────────── [requires approval] NuGet push + Git tag + GitHub Release
27+
|
28+
v
29+
deploy-docs ────── DocFX to GitHub Pages (optional)
30+
```
31+
32+
On **pull requests**, only a fast linux build + test runs. On **main**, the full multi-platform pipeline kicks in.
33+
34+
### Pipeline Highlights
35+
36+
| Feature | Details |
37+
|---------|---------|
38+
| **NUKE Build** | All build logic lives in C# targets -- no scattered shell scripts in YAML |
39+
| **Single Approval** | One `release` environment gate controls the entire release flow |
40+
| **Multi-Platform Matrix** | linux-x64, win-x64, osx-arm64 (+ optional Android/iOS) |
41+
| **NuGet Publishing** | Auto-push to NuGet.org with SHA256 manifest verification |
42+
| **Installer Packages** | Platform-specific zip archives attached to GitHub Releases |
43+
| **Version from Code** | `VersionPrefix` in `Directory.Build.props` is the single source of truth |
44+
| **Four-Part Release Tags** | `v0.2.0.42` format ensures unique tags per build |
45+
| **CodeQL Security** | Automated vulnerability scanning on every push and weekly |
46+
| **Graceful Degradation** | Missing NuGet key? Skipped. No DocFX config? Skipped. Nothing breaks. |
47+
48+
---
49+
50+
## Quick Start
51+
52+
### 1. Create your repo from this template
53+
54+
Click **[Use this template](https://github.com/AGIBuild/dotnet.CI.template/generate)** on GitHub.
55+
56+
### 2. Configure environments
57+
58+
Go to **Settings > Environments** and create a `release` environment with at least one required reviewer.
59+
60+
### 3. Set secrets (optional)
61+
62+
| Secret | Purpose |
63+
|--------|---------|
64+
| `NUGET_API_KEY` | Push packages to NuGet.org |
65+
66+
### 4. Push code and watch it go
67+
68+
```bash
69+
git push origin main
70+
```
71+
72+
The pipeline runs automatically. When `build-and-test` completes, go to **Actions > Review deployments** to approve the release.
73+
74+
---
75+
76+
## Project Structure
77+
78+
```
79+
.
80+
├── .github/workflows/
81+
│ ├── ci.yml # CI + Release pipeline
82+
│ └── codeql.yml # Security analysis
83+
├── build/
84+
│ ├── BuildTask.*.cs # NUKE targets (Build, Test, Pack, Publish, PackageApp, ...)
85+
│ └── _build.csproj
86+
├── src/ # Your application code
87+
├── tests/ # Your test projects
88+
├── docs/ # Guides (add docfx.json for auto-deploy)
89+
├── Directory.Build.props # Version + shared build properties
90+
└── global.json # SDK version pinning
91+
```
92+
93+
---
94+
95+
## Version Management
96+
97+
Versions follow a simple rule:
98+
99+
- **Edit `VersionPrefix`** in `Directory.Build.props` via PR (e.g., `0.2.0` -> `1.0.0`)
100+
- **CI appends the build number** on release: `0.2.0` becomes `0.2.0.42`
101+
- **Tags are created automatically**: `v0.2.0.42`
102+
103+
No manual tagging. No version input fields. Just change the number in one file.
104+
105+
---
106+
107+
## Extending the Build
108+
109+
Build logic is in `build/BuildTask.*.cs` using [NUKE](https://nuke.build). Add new targets in C# and call them from workflows:
110+
111+
```csharp
112+
Target MyTarget => _ => _
113+
.DependsOn(Build)
114+
.Executes(() =>
115+
{
116+
// your build logic here
117+
});
118+
```
119+
120+
```yaml
121+
# in ci.yml
122+
- run: ./build.sh MyTarget
123+
```
124+
125+
---
126+
127+
## Mobile Platform Support
128+
129+
Android and iOS builds are supported but disabled by default. Toggle them in `ci.yml`:
130+
131+
```yaml
132+
env:
133+
ENABLE_ANDROID: 'true'
134+
ENABLE_IOS: 'true'
135+
```
136+
137+
---
138+
139+
## Documentation Deployment
140+
141+
To enable automatic documentation deployment to GitHub Pages:
142+
143+
1. Add a `docs/docfx.json` configuration file
144+
2. Enable GitHub Pages in **Settings > Pages > Source: GitHub Actions**
145+
3. The `deploy-docs` job will automatically build and deploy after each release
146+
147+
---
148+
149+
## License
150+
151+
[MIT](LICENSE)

‎docs/github-workflows-guide.md‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,8 @@ push / PR to main
1010
└─ CI and Release
1111
├─ resolve-version
1212
├─ build-and-test (matrix: PR=linux, main=全平台)
13-
├─ release-packages (需 approval，推 NuGet)
14-
├─ deploy-docs (GitHub Pages)
15-
└─ create-release (tag + GitHub Release)
13+
├─ release (需 approval，NuGet 推送 + tag + GitHub Release)
14+
└─ deploy-docs (GitHub Pages)
1615
1716
push / PR to main + weekly
1817
└─ CodeQL (security scan)
@@ -27,8 +26,8 @@ push / PR to main + weekly
2726
### `CI and Release`
2827
- 触发：`push` 到 `main`、对 `main` 的 `pull_request`、手动 `workflow_dispatch`
2928
- PR 行为：只在 ubuntu 上运行 Build + Test（带 prerelease suffix）
30-
- main push 行为：全平台矩阵 Build + Test + Pack + Publish → approval → NuGet 推送 → 文档部署 → GitHub Release
31-
- 产物：测试结果、NuGet 包（含 release manifest）、各平台安装包
29+
- main push 行为：全平台矩阵 Build + Test + Pack + Publish + PackageApp → approval → NuGet 推送 + tag + GitHub Release → 文档部署
30+
- 产物：测试结果、NuGet 包（含 release manifest）、各平台安装包 zip
3231

3332
### `CodeQL`
3433
- 触发：`push`/`pull_request` 到 `main`，以及每周定时任务
@@ -49,23 +48,20 @@ push / PR to main + weekly
4948
- PR：带 `--VersionSuffix "ci.<run_number>"`
5049
- main push：无 suffix（固化 release 版本）
5150
- linux runner 额外执行 Pack + GenerateReleaseManifest（生成 SHA256 manifest）
52-
- 各平台执行 Publish 生成安装包
51+
- 各平台执行 Publish + PackageApp，生成安装包 zip（`app-{runtime}.zip`）
5352

54-
### `release-packages`
53+
### `release`
5554
- 需要 `release` environment approval（唯一的审批入口）
5655
- 下载 NuGet 包，验证 release manifest SHA256 完整性
57-
- 推送 NuGet 包到 nuget.org
56+
- 推送 NuGet 包到 nuget.org（如未配置 `NUGET_API_KEY` 则跳过）
57+
- 创建 git tag 并推送到 remote
58+
- 创建 GitHub Release，附带各平台安装包 zip（不含 NuGet 包）
5859

5960
### `deploy-docs`
60-
- 依赖 `release-packages` 成功后自动运行
61+
- 依赖 `release` 成功后自动运行
6162
- 如果存在 `docs/docfx.json`，构建 DocFX 并部署到 GitHub Pages
6263
- 如果不存在则跳过
6364

64-
### `create-release`
65-
- 依赖 `release-packages` 和 `deploy-docs` 完成
66-
- 创建 git tag 并推送到 remote
67-
- 创建 GitHub Release，附带所有产物（NuGet 包 + 安装包 zip）
68-
6965
---
7066

7167
## 3) 最快上手路径（推荐）
@@ -77,8 +73,9 @@ push / PR to main + weekly
7773
审批 `release` environment。
7874

7975
3. 去 Releases 页面确认：
80-
- 已创建 tag（如 `v0.1.0`）
81-
- 已生成 `.nupkg` / `.snupkg` + 安装包 zip
76+
- 已创建 tag（如 `v0.2.0.42`）
77+
- GitHub Release 中已生成各平台安装包 zip
78+
- NuGet.org 上有对应版本的包（如已配置 `NUGET_API_KEY`）
8279

8380
---
8481

@@ -108,7 +105,7 @@ push / PR to main + weekly
108105
通过 PR 修改 `VersionPrefix`（例如 `0.1.0 -> 0.2.0`），合并到 `main` 后 CI 自动基于新版本构建。
109106

110107
### Q3: 同一版本能否重新发布？
111-
不能。如果 tag 已存在，`create-release` 会直接失败。需要先提升 `VersionPrefix`。
108+
每次 main push 都会生成唯一的四段式版本号（如 `0.2.0.42`），因此同一 push 不会冲突。如果需要发新版本（如 `0.3.0`），通过 PR 修改 `VersionPrefix`。
112109

113110
### Q4: Release manifest 是什么？
114111
`release-manifest.json` 记录每个 NuGet 包的 SHA256 hash 和版本信息。发布阶段会验证包文件与 manifest 一致，防止产物在传递过程中被篡改或损坏。

‎docs/quick-start-release.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,16 @@
1616

1717
## 1) Release 流程概览
1818

19-
Release 集成在 `CI and Release` workflow 中，由 5 个 job 串联完成：
19+
Release 集成在 `CI and Release` workflow 中，由 4 个 job 串联完成：
2020

2121
```text
22-
resolve-version → build-and-test (matrix) → release-packages (需 approve) → deploy-docs → create-release
22+
resolve-version → build-and-test (matrix) → release (需 approve) → deploy-docs
2323
```
2424

2525
当代码 push 到 `main` 后：
26-
1. CI 自动构建、测试、打包（NuGet 包 + 安装包）
27-
2. `release-packages` job 等待 `release` environment 的 **reviewer approval**
28-
3. Approve 后自动完成：NuGet 推送 → 文档部署 → 创建 tag + GitHub Release
26+
1. CI 自动构建、测试、打包（NuGet 包 + 平台安装包 zip）
27+
2. `release` job 等待 `release` environment 的 **reviewer approval**
28+
3. Approve 后自动完成：NuGet 推送 → 创建 tag + GitHub Release（仅含安装包 zip） → 文档部署
2929

3030
---
3131

@@ -41,9 +41,9 @@ resolve-version → build-and-test (matrix) → release-packages (需 approve)
4141

4242
运行成功后应看到：
4343

44-
- 新 tag（例如 `v0.1.0`）
44+
- 新 tag（例如 `v0.2.0.42`）
4545
- 一个新的 GitHub Release
46-
- Release 附件里有 `.nupkg` / `.snupkg` 和各平台安装包 zip
46+
- Release 附件里有各平台安装包 zip（`app-linux-x64.zip`、`app-win-x64.zip` 等）
4747
- NuGet.org 上有对应版本的包（如已配置 `NUGET_API_KEY`）
4848

4949
---

0 commit comments

Comments
 (0)