hve-core · GitVita

1

---

2

title: Build Workflows

3

description: GitHub Actions CI/CD pipeline architecture for validation, security, and release automation

4

author: WilliamBerryiii

5

ms.date: 2026-02-10

ms.topic: overview

---

HVE 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.

10

11

## Pipeline Overview

```mermaid

flowchart TD

subgraph PR["Pull Request"]

16

direction TB

17

PR1[PR Opened/Updated] --> PV[pr-validation.yml]

18

PV --> LINT[Linting Jobs]

19

PV --> SEC[Security Jobs]

20

PV --> TEST[Test Jobs]

21

end

22

23

subgraph MAIN["Main Branch"]

24

direction TB

25

MERGE[Merge to Main] --> MN[main.yml]

26

MN --> VAL[Validation]

27

VAL --> PKG[Extension Package]

28

PKG --> REL[Release Please]

29

end

30

31

subgraph SCHED["Scheduled"]

32

direction TB

33

CRON[Weekly Sunday 2AM] --> WEEKLY[weekly-security-maintenance.yml]

34

WEEKLY --> SECCHECK[Security Checks]

35

end

36

37

subgraph MANUAL["Manual"]

38

direction TB

39

DISPATCH[Manual Trigger] --> PUB[extension-publish.yml]

40

PUB --> VSCE[Publish to Marketplace]

end

```

## Workflow Inventory

45

46

| Workflow | Trigger | Purpose |

47

|------------------------------------|----------------|-------------------------------------------------|

48

| `pr-validation.yml` | Pull request | Pre-merge quality gate with parallel validation |

49

| `main.yml` | Push to main | Post-merge validation and release automation |

50

| `weekly-security-maintenance.yml` | Sunday 2AM UTC | Scheduled security posture review |

51

| `extension-publish.yml` | Manual | VS Code extension marketplace publishing |

52

| `extension-publish-prerelease.yml` | Manual | VS Code extension pre-release publishing |

53

54

### Reusable Workflows

55

56

Individual validation workflows called by orchestration workflows:

57

58

| Workflow | Purpose | npm Script |

59

|-------------------------------|---------------------------------|----------------------------|

60

| `markdown-lint.yml` | Markdownlint validation | `npm run lint:md` |

61

| `spell-check.yml` | cspell dictionary check | `npm run spell-check` |

62

| `frontmatter-validation.yml` | AI artifact frontmatter schemas | `npm run lint:frontmatter` |

63

| `markdown-link-check.yml` | Broken link detection | `npm run lint:md-links` |

64

| `link-lang-check.yml` | Link language validation | `npm run lint:links` |

65

| `yaml-lint.yml` | YAML syntax validation | `npm run lint:yaml` |

66

| `ps-script-analyzer.yml` | PowerShell static analysis | `npm run lint:ps` |

67

| `table-format.yml` | Markdown table formatting | `npm run format:tables` |

68

| `pester-tests.yml` | PowerShell unit tests | `npm run test:ps` |

69

| `dependency-pinning-scan.yml` | GitHub Actions pinning | N/A (PowerShell direct) |

70

| `sha-staleness-check.yml` | SHA reference freshness | N/A (PowerShell direct) |

71

| `codeql-analysis.yml` | CodeQL security scanning | N/A (GitHub native) |

72

| `dependency-review.yml` | Dependency vulnerability review | N/A (GitHub native) |

73

| `security-scan.yml` | Composite security validation | N/A |

74

| `extension-package.yml` | VS Code extension packaging | N/A |

75

76

## PR Validation Pipeline

77

78

The `pr-validation.yml` workflow serves as the primary quality gate for all pull requests. It runs 12 parallel jobs covering linting, security, and testing.

```mermaid

flowchart LR

subgraph "Linting"

ML[markdown-lint]

SC[spell-check]

TF[table-format]

YL[yaml-lint]

FV[frontmatter-validation]

88

LLC[link-lang-check]

89

MLC[markdown-link-check]

90

end

91

92

subgraph "Analysis"

93

PSA[psscriptanalyzer]

PT[pester-tests]

end

subgraph "Security"

98

DPC[dependency-pinning-check]

NA[npm-audit]

CQL[codeql]

end

```

### Jobs

| Job | Reusable Workflow | Validates |

107

|--------------------------|-------------------------------|--------------------------------|

108

| spell-check | `spell-check.yml` | Spelling across all files |

109

| markdown-lint | `markdown-lint.yml` | Markdown formatting rules |

110

| table-format | `table-format.yml` | Markdown table structure |

111

| psscriptanalyzer | `ps-script-analyzer.yml` | PowerShell code quality |

112

| yaml-lint | `yaml-lint.yml` | YAML syntax |

113

| pester-tests | `pester-tests.yml` | PowerShell unit tests |

114

| frontmatter-validation | `frontmatter-validation.yml` | AI artifact metadata |

115

| link-lang-check | `link-lang-check.yml` | Link accessibility |

116

| markdown-link-check | `markdown-link-check.yml` | Broken links |

117

| dependency-pinning-check | `dependency-pinning-scan.yml` | Action SHA pinning |

118

| npm-audit | Inline | npm dependency vulnerabilities |

119

| codeql | `codeql-analysis.yml` | Code security patterns |

120

121

All jobs run in parallel with no dependencies, enabling fast feedback (typically under 3 minutes).

122

123

## Main Branch Pipeline

124

125

The `main.yml` workflow runs after merges to main, performing validation and release automation.

```mermaid

flowchart LR

V1[spell-check] --> RP[release-please]

130

V2[markdown-lint] --> RP

131

V3[table-format] --> RP

132

V4[dependency-pinning-scan] --> RP

133

V5[pester-tests] --> RP

134

RP -->|release_created| PKG[extension-package-release]

135

PKG --> ATT[attest-and-upload]

136

style RP fill:#f9f,stroke:#333

137

```

138

139

Release-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.

140

141

### Main Branch Jobs

142

143

| Job | Purpose | Dependencies |

144

|---------------------------|--------------------------------|------------------------------|

145

| spell-check | Post-merge spelling validation | None |

146

| markdown-lint | Post-merge markdown validation | None |

147

| table-format | Post-merge table validation | None |

148

| dependency-pinning-scan | Security pinning check | None |

149

| pester-tests | PowerShell unit tests | None |

150

| release-please | Automated release management | All validation jobs |

151

| extension-package-release | Build release VSIX | release-please (conditional) |

152

| attest-and-upload | Sign and upload VSIX | extension-package-release |

153

154

When release-please creates a release, the `extension-package-release` job builds the VSIX with the correct version, and `attest-and-upload` signs it with Sigstore attestation before uploading to the GitHub Release.

155

156

## Security Workflows

157

158

### Weekly Security Maintenance

159

160

The `weekly-security-maintenance.yml` workflow runs every Sunday at 2AM UTC, providing scheduled security posture review.

161

162

| Job | Purpose |

163

|------------------|---------------------------------------|

164

| validate-pinning | Verify GitHub Actions use SHA pinning |

165

| check-staleness | Detect outdated SHA references |

166

| codeql-analysis | Full CodeQL security scan |

167

| summary | Aggregate security status report |

168

169

### Security Validation Tools

170

171

| Tool | Script | Checks |

172

|--------------------|------------------------------|------------------------------------------|

173

| Dependency Pinning | `Test-DependencyPinning.ps1` | Actions use SHA refs, not tags |

174

| SHA Staleness | `Test-SHAStaleness.ps1` | SHAs reference recent commits |

175

| npm Audit | `npm audit` | Known vulnerabilities in dependencies |

176

| CodeQL | GitHub native | Code patterns indicating security issues |

177

178

## Extension Publishing

179

180

The `extension-publish.yml` and `extension-publish-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.

```mermaid

flowchart LR

PC[prepare-changelog] --> DC[discover-collections]

185

NV[normalize-version] --> DC

186

DC --> PKG["package (matrix)"]

187

PKG --> PUB["publish (matrix)"]

188

```

189

190

### Publishing Jobs

191

192

| Job | Purpose |

193

|----------------------|-------------------------------------------------------------|

194

| prepare-changelog | Extract release notes from CHANGELOG.md |

195

| normalize-version | Ensure version consistency |

196

| validate-version | Enforce ODD minor version for pre-release channel |

197

| discover-collections | Scan collection manifests, filter by maturity and channel |

198

| package (matrix) | Build one VSIX per collection using `extension-package.yml` |

199

| publish (matrix) | Upload each VSIX to VS Code Marketplace via OIDC + vsce |

200

201

### Collection-Based Packaging

202

203

Collection 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.

204

205

| Collection | Maturity | Included In |

206

|----------------|--------------|--------------------|

207

| `hve-core-all` | Stable | Stable, PreRelease |

208

| `developer` | Experimental | PreRelease only |

209

210

Maturity filtering rules:

211

212

* **Deprecated** collections are always excluded.

213

* **Experimental** collections are excluded from Stable channel builds.

214

* **Stable** collections are included in all channel builds.

215

216

### Version Channels

217

218

| Channel | Version Pattern | Marketplace |

219

|-------------|--------------------|------------------|

220

| Stable | Even minor (1.2.0) | Main listing |

221

| Pre-release | Odd minor (1.3.0) | Pre-release flag |

222

223

## npm Script Mapping

224

225

Workflows invoke validation through npm scripts defined in `package.json`:

226

227

| npm Script | Command | Used By |

228

|--------------------|------------------------------------|----------------------------|

229

| `lint:md` | `markdownlint-cli2` | markdown-lint.yml |

230

| `spell-check` | `cspell` | spell-check.yml |

231

| `lint:frontmatter` | `Validate-MarkdownFrontmatter.ps1` | frontmatter-validation.yml |

232

| `lint:md-links` | `Markdown-Link-Check.ps1` | markdown-link-check.yml |

233

| `lint:links` | `Invoke-LinkLanguageCheck.ps1` | link-lang-check.yml |

234

| `lint:yaml` | `Invoke-YamlLint.ps1` | yaml-lint.yml |

235

| `lint:ps` | `Invoke-PSScriptAnalyzer.ps1` | ps-script-analyzer.yml |

236

| `format:tables` | `markdown-table-formatter` | table-format.yml |

237

| `test:ps` | `Invoke-Pester` | pester-tests.yml |

238

239

## Related Documentation

240

241

* [Testing Architecture](testing.md) - PowerShell Pester test infrastructure

242

* [Scripts README](../../scripts/README.md) - Script organization and usage

243

244

🤖 *Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*

245

microsoft/hve-core

Branches

Tags

Clone

docs/architecture/workflows.md