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

| `skill-validation.yml` | Skill structure validation | `npm run validate:skills` |

70

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

71

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

72

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

73

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

74

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

75

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

76

77

## PR Validation Pipeline

78

79

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]

89

LLC[link-lang-check]

90

MLC[markdown-link-check]

91

end

92

93

subgraph "Analysis"

94

PSA[psscriptanalyzer]

PT[pester-tests]

end

subgraph "Security"

99

DPC[dependency-pinning-check]

NA[npm-audit]

CQL[codeql]

end

```

### Jobs

| Job | Reusable Workflow | Validates |

108

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

109

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

110

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

111

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

112

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

113

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

114

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

115

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

116

| skill-validation | `skill-validation.yml` | Skill directory structure |

117

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

118

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

119

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

120

| npm-audit | Inline | npm dependency vulnerabilities |

121

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

122

123

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

124

125

## Main Branch Pipeline

126

127

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

```mermaid

flowchart LR

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

132

V2[markdown-lint] --> RP

133

V3[table-format] --> RP

134

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

135

V5[pester-tests] --> RP

136

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

137

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

138

style RP fill:#f9f,stroke:#333

139

```

140

141

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.

142

143

### Main Branch Jobs

144

145

| Job | Purpose | Dependencies |

146

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

147

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

148

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

149

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

150

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

151

| pester-tests | PowerShell unit tests | None |

152

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

153

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

154

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

155

156

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.

157

158

## Security Workflows

159

160

### Weekly Security Maintenance

161

162

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

163

164

| Job | Purpose |

165

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

166

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

167

| check-staleness | Detect outdated SHA references |

168

| codeql-analysis | Full CodeQL security scan |

169

| summary | Aggregate security status report |

170

171

### Security Validation Tools

172

173

| Tool | Script | Checks |

174

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

175

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

176

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

177

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

178

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

179

180

## Extension Publishing

181

182

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]

187

NV[normalize-version] --> DC

188

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

189

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

190

```

191

192

### Publishing Jobs

193

194

| Job | Purpose |

195

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

196

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

197

| normalize-version | Ensure version consistency |

198

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

199

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

200

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

201

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

202

203

### Collection-Based Packaging

204

205

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.

206

207

| Collection | Maturity | Included In |

208

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

209

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

210

| `developer` | Experimental | PreRelease only |

211

212

Maturity filtering rules:

213

214

* **Deprecated** collections are always excluded.

215

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

216

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

217

218

### Version Channels

219

220

| Channel | Version Pattern | Marketplace |

221

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

222

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

223

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

224

225

## npm Script Mapping

226

227

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

228

229

| npm Script | Command | Used By |

230

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

231

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

232

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

233

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

234

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

235

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

236

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

237

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

238

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

239

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

240

| `validate:skills` | `Validate-SkillStructure.ps1` | skill-validation.yml |

241

242

## Related Documentation

243

244

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

245

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

246

247

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

248

microsoft/hve-core

Branches

Tags

Clone

docs/architecture/workflows.md