GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
hve-core-v3.3.27

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/architecture

docs/architecture/workflows.md

317lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: Build Workflows
3description: GitHub Actions CI/CD pipeline architecture for validation, security, and release automation
4sidebar_position: 3
5author: WilliamBerryiii
6ms.date: 2026-02-10
7ms.topic: overview
8---
9
10HVE Core uses GitHub Actions for continuous integration, quality validation, security scanning, and release automation. The workflow architecture emphasizes reusable components and parallel execution for fast feedback.
11
12## Pipeline Overview
13
14```mermaid
15flowchart TD
16 subgraph PR["Pull Request"]
17 direction TB
18 PR1[PR Opened/Updated] --> PV[pr-validation.yml]
19 PV --> LINT[Linting Jobs]
20 PV --> SEC[Security Jobs]
21 PV --> TEST[Test Jobs]
22 end
23
24 subgraph MAIN["Main Branch"]
25 direction TB
26 MERGE[Merge to Main] --> MN[release-stable.yml]
27 MN --> VAL[Validation]
28 VAL --> PKG[Extension Package]
29 PKG --> REL[Release Please]
30 end
31
32 subgraph SCHED["Scheduled"]
33 direction TB
34 CRON[Weekly Sunday 2AM] --> WEEKLY[weekly-security-maintenance.yml]
35 WEEKLY --> SECCHECK[Security Checks]
36 end
37
38 subgraph MANUAL["Manual"]
39 direction TB
40 DISPATCH[Manual Trigger] --> PUB[release-marketplace-stable.yml]
41 PUB --> VSCE[Publish to Marketplace]
42 end
43```
44
45## Workflow Inventory
46
47| Workflow | Trigger | Purpose |
48|--------------------------------------|-------------------------|-------------------------------------------------------------------|
49| `pr-validation.yml` | Pull request, manual | Pre-merge quality gate with parallel validation |
50| `release-stable.yml` | Push to main, manual | Post-merge validation and release automation |
51| `weekly-security-maintenance.yml` | Sunday 2 AM UTC, manual | Scheduled security posture review |
52| `security-scan.yml` | Push to main/develop | CodeQL security validation |
53| `release-marketplace-stable.yml` | Manual | VS Code extension marketplace publishing |
54| `release-marketplace-prerelease.yml` | Manual | VS Code extension pre-release publishing |
55| `copilot-setup-steps.yml` | Manual | Coding agent environment setup |
56| `devcontainer-change-log.yml` | Push to main/develop | Logs devcontainer infrastructure file changes to the step summary |
57| `release-prerelease.yml` | PR closed | Pre-release tag and publish on merge to main |
58| `release-prerelease-pr.yml` | Push to main | Pre-release companion PR management |
59| `scorecard.yml` | Schedule, push | OpenSSF Scorecard security analysis |
60| `codeql-analysis.yml` | Schedule | Weekly CodeQL security scan (also reusable) |
61| `dependency-review.yml` | Pull request | Dependency vulnerability review (also reusable) |
62| `sha-staleness-check.yml` | Manual | SHA reference freshness check (also reusable) |
63
64### Reusable Workflows
65
66Individual validation workflows called by orchestration workflows:
67
68| Workflow | Purpose | npm Script |
69|-------------------------------------|----------------------------------|-------------------------------------|
70| `markdown-lint.yml` | Markdownlint validation | `npm run lint:md` |
71| `spell-check.yml` | cspell dictionary check | `npm run spell-check` |
72| `frontmatter-validation.yml` | AI artifact frontmatter schemas | `npm run lint:frontmatter` |
73| `markdown-link-check.yml` | Broken link detection | `npm run lint:md-links` |
74| `link-lang-check.yml` | Link language validation | `npm run lint:links` |
75| `yaml-lint.yml` | YAML syntax validation | `npm run lint:yaml` |
76| `ps-script-analyzer.yml` | PowerShell static analysis | `npm run lint:ps` |
77| `table-format.yml` | Markdown table formatting | `npm run format:tables` |
78| `pester-tests.yml` | PowerShell unit tests | `npm run test:ps` |
79| `skill-validation.yml` | Skill structure validation | `npm run validate:skills` |
80| `dependency-pinning-scan.yml` | Dependency pinning validation | N/A (PowerShell direct) |
81| `sha-staleness-check.yml` | SHA reference freshness* | N/A (PowerShell direct) |
82| `codeql-analysis.yml` | CodeQL security scanning* | N/A (GitHub native) |
83| `dependency-review.yml` | Dependency vulnerability review* | N/A (GitHub native) |
84| `extension-package.yml` | VS Code extension packaging | `npm run extension:package` |
85| `copyright-headers.yml` | Copyright header validation | `npm run validate:copyright` |
86| `gitleaks-scan.yml` | Secret detection scanning | N/A (gitleaks direct) |
87| `plugin-package.yml` | Plugin collection packaging | N/A |
88| `plugin-validation.yml` | Plugin and collection metadata | `npm run lint:collections-metadata` |
89| `extension-marketplace-publish.yml` | Extension marketplace publishing | N/A |
90
91Workflows marked with `*` are dual-purpose: they accept `workflow_call` for reuse by orchestration workflows and also run independently via their own triggers.
92
93## PR Validation Pipeline
94
95The `pr-validation.yml` workflow serves as the primary quality gate for all pull requests. It runs 16 parallel jobs covering linting, security, and testing.
96
97```mermaid
98flowchart LR
99 subgraph "Linting"
100 ML[markdown-lint]
101 SC[spell-check]
102 TF[table-format]
103 YL[yaml-lint]
104 FV[frontmatter-validation]
105 LLC[link-lang-check]
106 MLC[markdown-link-check]
107 CH[copyright-headers]
108 end
109
110 subgraph "Analysis"
111 PSA[psscriptanalyzer]
112 PT[pester-tests]
113 SV[skill-validation]
114 PV[plugin-validation]
115 end
116
117 subgraph "Security"
118 DPC[dependency-pinning-check]
119 NA[npm-audit]
120 CQL[codeql]
121 GLS[gitleaks-scan]
122 end
123```
124
125### Jobs
126
127| Job | Reusable Workflow | Validates |
128|--------------------------|-------------------------------|--------------------------------|
129| spell-check | `spell-check.yml` | Spelling across all files |
130| markdown-lint | `markdown-lint.yml` | Markdown formatting rules |
131| table-format | `table-format.yml` | Markdown table structure |
132| psscriptanalyzer | `ps-script-analyzer.yml` | PowerShell code quality |
133| yaml-lint | `yaml-lint.yml` | YAML syntax |
134| pester-tests | `pester-tests.yml` | PowerShell unit tests |
135| frontmatter-validation | `frontmatter-validation.yml` | AI artifact metadata |
136| skill-validation | `skill-validation.yml` | Skill directory structure |
137| link-lang-check | `link-lang-check.yml` | Link accessibility |
138| markdown-link-check | `markdown-link-check.yml` | Broken links |
139| dependency-pinning-check | `dependency-pinning-scan.yml` | Dependency pinning |
140| npm-audit | Inline | npm dependency vulnerabilities |
141| codeql | `codeql-analysis.yml` | Code security patterns |
142| copyright-headers | `copyright-headers.yml` | Copyright header compliance |
143| plugin-validation | `plugin-validation.yml` | Plugin and collection metadata |
144| gitleaks-scan | `gitleaks-scan.yml` | Secret detection |
145
146All jobs run in parallel with no dependencies, enabling fast feedback (typically under 3 minutes).
147
148## Main Branch Pipeline
149
150The `release-stable.yml` workflow runs after merges to main, performing validation and release automation.
151
152```mermaid
153flowchart LR
154 V1[spell-check] --> RP[release-please]
155 V2[markdown-lint] --> RP
156 V3[table-format] --> RP
157 V4[dependency-pinning-scan] --> RP
158 V5[gitleaks-scan] --> RP
159 V6[pester-tests] --> RP
160 RP --> RST[reset-prerelease]
161 RP -->|release_created| EPR[extension-package-release]
162 RP -->|release_created| PPR[plugin-package-release]
163 RP -->|release_created| SBOM[generate-dependency-sbom]
164 EPR --> ATT[attest-and-upload]
165 SBOM --> ATT
166 PPR --> UPP[upload-plugin-packages]
167 SBOM --> SD[sbom-diff]
168 ATT --> PUB[publish-release]
169 UPP --> PUB
170 SD --> PUB
171 style RP fill:#f9f,stroke:#333
172```
173
174Release-please v4 handles `chore`-type commits natively. They are not releasable and do not produce spurious release PRs, so no commit-message guard is needed.
175
176### Main Branch Jobs
177
178| Job | Purpose | Dependencies |
179|---------------------------|--------------------------------|----------------------------------------------------------------------|
180| spell-check | Post-merge spelling validation | None |
181| markdown-lint | Post-merge markdown validation | None |
182| table-format | Post-merge table validation | None |
183| dependency-pinning-scan | Security pinning check | None |
184| gitleaks-scan | Secret detection scanning | None |
185| pester-tests | PowerShell unit tests | None |
186| release-please | Automated release management | All validation jobs |
187| reset-prerelease | Reset pre-release tracking | release-please |
188| extension-package-release | Build release VSIX | release-please (conditional) |
189| plugin-package-release | Build release plugin packages | release-please (conditional) |
190| generate-dependency-sbom | Generate dependency SBOM | release-please (conditional) |
191| attest-and-upload | Sign and upload VSIX | release-please, extension-package-release, generate-dependency-sbom |
192| upload-plugin-packages | Upload plugin packages | release-please, plugin-package-release |
193| sbom-diff | Compare SBOM changes | release-please, generate-dependency-sbom |
194| publish-release | Finalize GitHub Release | release-please, attest-and-upload, upload-plugin-packages, sbom-diff |
195
196When release-please creates a release, parallel jobs build the extension VSIX (`extension-package-release`), package plugin collections (`plugin-package-release`), and generate an SBOM (`generate-dependency-sbom`). The `attest-and-upload` job signs the VSIX with Sigstore attestation, `upload-plugin-packages` uploads collection artifacts, and `sbom-diff` compares dependency changes. The `publish-release` job finalizes the GitHub Release after all artifacts are ready.
197
198## Security Workflows
199
200### Weekly Security Maintenance
201
202The `weekly-security-maintenance.yml` workflow runs every Sunday at 2AM UTC, providing scheduled security posture review.
203
204| Job | Purpose |
205|------------------|--------------------------------------|
206| validate-pinning | Verify dependency pinning compliance |
207| check-staleness | Detect outdated SHA references |
208| codeql-analysis | Full CodeQL security scan |
209| summary | Aggregate security status report |
210
211### Security Validation Tools
212
213| Tool | Script | Checks |
214|--------------------|------------------------------|-----------------------------------------------|
215| Dependency Pinning | `Test-DependencyPinning.ps1` | Actions use SHA refs; npm uses exact versions |
216| SHA Staleness | `Test-SHAStaleness.ps1` | SHAs reference recent commits |
217| npm Audit | `npm audit` | Known vulnerabilities in dependencies |
218| CodeQL | GitHub native | Code patterns indicating security issues |
219| Gitleaks | `gitleaks` | Secret detection in repository history |
220| Dependency Review | GitHub native | Dependency vulnerability analysis |
221
222## Extension Publishing
223
224The `release-marketplace-stable.yml` and `release-marketplace-prerelease.yml` workflows handle VS Code extension marketplace publishing through manual dispatch. Both workflows use collection-based packaging to produce and publish a separate VSIX per collection.
225
226```mermaid
227flowchart TD
228 subgraph Stable["release-marketplace-stable.yml"]
229 NV[normalize-version] --> PKG1["package (matrix)"]
230 PKG1 --> PUB1["publish (matrix)"]
231 end
232 subgraph PreRelease["release-marketplace-prerelease.yml"]
233 VV[validate-version] --> PKG2["package (matrix)"]
234 PKG2 --> PUB2["publish (matrix)"]
235 end
236```
237
238### Publishing Jobs
239
240| Job | Purpose | Workflow |
241|-------------------|-------------------------------------------------------------|--------------------------------------|
242| normalize-version | Ensure version consistency | `release-marketplace-stable.yml` |
243| validate-version | Enforce odd minor version for pre-release channel | `release-marketplace-prerelease.yml` |
244| package (matrix) | Build one VSIX per collection using `extension-package.yml` | Both |
245| publish (matrix) | Upload each VSIX to VS Code Marketplace via OIDC + vsce | Both |
246
247### Collection-Based Packaging
248
249Collection manifests in `collections/*.collection.yml` define collection-scoped subsets of the full artifact set. The `extension-package.yml` reusable workflow discovers these manifests, filters by maturity and channel, and packages each as an independent VSIX.
250
251| Collection | Maturity | Included In |
252|--------------------|--------------|--------------------|
253| `hve-core-all` | Stable | Stable, PreRelease |
254| `hve-core` | Stable | Stable, PreRelease |
255| `ado` | Stable | Stable, PreRelease |
256| `github` | Stable | Stable, PreRelease |
257| `project-planning` | Stable | Stable, PreRelease |
258| `coding-standards` | Stable | Stable, PreRelease |
259| `data-science` | Stable | Stable, PreRelease |
260| `security` | Experimental | Stable, PreRelease |
261| `design-thinking` | Preview | Stable, PreRelease |
262| `installer` | Stable | Stable, PreRelease |
263| `experimental` | Experimental | PreRelease only |
264
265Maturity filtering rules:
266
267| Maturity Level | Build Inclusion |
268|----------------|-------------------------------------------------|
269| Deprecated | Always excluded |
270| Experimental | Excluded from Stable channel builds |
271| Preview | Included in both Stable and PreRelease channels |
272| Stable | Included in all channel builds |
273
274### Version Channels
275
276| Channel | Version Pattern | Marketplace |
277|-------------|--------------------|------------------|
278| Stable | Even minor (1.2.0) | Main listing |
279| Pre-release | Odd minor (1.3.0) | Pre-release flag |
280
281## npm Script Mapping
282
283Workflows invoke validation through npm scripts defined in `package.json`:
284
285| npm Script | Command | Used By |
286|--------------------------------|---------------------------------------------|----------------------------|
287| `lint:md` | `markdownlint-cli2` | markdown-lint.yml |
288| `lint:md:fix` | `markdownlint-cli2 --fix` | Local |
289| `spell-check` | `cspell` | spell-check.yml |
290| `spell-check:fix` | `cspell --show-suggestions` | Local |
291| `lint:frontmatter` | `Validate-MarkdownFrontmatter.ps1` | frontmatter-validation.yml |
292| `lint:md-links` | `Markdown-Link-Check.ps1` | markdown-link-check.yml |
293| `lint:links` | `Invoke-LinkLanguageCheck.ps1` | link-lang-check.yml |
294| `lint:yaml` | `Invoke-YamlLint.ps1` | yaml-lint.yml |
295| `lint:ps` | `Invoke-PSScriptAnalyzer.ps1` | ps-script-analyzer.yml |
296| `lint:collections-metadata` | `Validate-Collections.ps1` | plugin-validation.yml |
297| `lint:marketplace` | `Validate-Marketplace.ps1` | plugin-validation.yml |
298| `lint:version-consistency` | `Test-ActionVersionConsistency.ps1` | Local |
299| `lint:all` | Chains all linters | Local |
300| `format:tables` | `markdown-table-formatter` | table-format.yml |
301| `test:ps` | `Invoke-PesterTests.ps1` | pester-tests.yml |
302| `validate:skills` | `Validate-SkillStructure.ps1` | skill-validation.yml |
303| `validate:copyright` | `Test-CopyrightHeaders.ps1` | copyright-headers.yml |
304| `extension:prepare` | `Prepare-Extension.ps1` | extension-package.yml |
305| `extension:prepare:prerelease` | `Prepare-Extension.ps1 -Channel PreRelease` | extension-package.yml |
306| `extension:package` | `Package-Extension.ps1` | extension-package.yml |
307| `package:extension` | Alias for `extension:package` | extension-package.yml |
308| `extension:package:prerelease` | `Package-Extension.ps1 -PreRelease` | extension-package.yml |
309| `plugin:generate` | `Generate-Plugins.ps1` + post-process | plugin-package.yml |
310| `plugin:validate` | Alias for `lint:collections-metadata` | plugin-validation.yml |
311
312## Related Documentation
313
314* [Testing Architecture](testing.md) - PowerShell Pester test infrastructure
315* [Scripts README](https://github.com/microsoft/hve-core/blob/main/scripts/README.md) - Script organization and usage
316
317🤖 *Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*
318