Build Workflows
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.
Pipeline Overview
Workflow Inventory
| Workflow | Trigger | Purpose |
|---|---|---|
pr-validation.yml | Pull request, manual | Pre-merge quality gate with parallel validation |
release-stable.yml | Push to main, manual | Post-merge validation and release automation |
weekly-security-maintenance.yml | Sunday 2 AM UTC, manual | Scheduled security posture review |
security-scan.yml | Push to main/develop | CodeQL security validation |
release-marketplace-stable.yml | Manual | VS Code extension marketplace publishing |
release-marketplace-prerelease.yml | Manual | VS Code extension pre-release publishing |
copilot-setup-steps.yml | Manual | Coding agent environment setup |
release-prerelease.yml | PR closed | Pre-release tag and publish on merge to main |
release-prerelease-pr.yml | Push to main | Pre-release companion PR management |
scorecard.yml | Schedule, push | OpenSSF Scorecard security analysis |
codeql-analysis.yml | Schedule | Weekly CodeQL security scan (also reusable) |
dependency-review.yml | Pull request | Dependency vulnerability review (also reusable) |
sha-staleness-check.yml | Manual | SHA reference freshness check (also reusable) |
Reusable Workflows
Individual validation workflows called by orchestration workflows:
| Workflow | Purpose | npm Script |
|---|---|---|
markdown-lint.yml | Markdownlint validation | npm run lint:md |
spell-check.yml | cspell dictionary check | npm run spell-check |
frontmatter-validation.yml | AI artifact frontmatter schemas | npm run lint:frontmatter |
markdown-link-check.yml | Broken link detection | npm run lint:md-links |
link-lang-check.yml | Link language validation | npm run lint:links |
yaml-lint.yml | YAML syntax validation | npm run lint:yaml |
ps-script-analyzer.yml | PowerShell static analysis | npm run lint:ps |
table-format.yml | Markdown table formatting | npm run format:tables |
pester-tests.yml | PowerShell unit tests | npm run test:ps |
skill-validation.yml | Skill structure validation | npm run validate:skills |
dependency-pinning-scan.yml | Dependency pinning validation | N/A (PowerShell direct) |
sha-staleness-check.yml | SHA reference freshness* | N/A (PowerShell direct) |
codeql-analysis.yml | CodeQL security scanning* | N/A (GitHub native) |
dependency-review.yml | Dependency vulnerability review* | N/A (GitHub native) |
extension-package.yml | VS Code extension packaging | npm run extension:package |
copyright-headers.yml | Copyright header validation | npm run validate:copyright |
gitleaks-scan.yml | Secret detection scanning | N/A (gitleaks direct) |
plugin-package.yml | Plugin collection packaging | N/A |
plugin-validation.yml | Plugin and collection metadata | npm run lint:collections-metadata |
extension-marketplace-publish.yml | Extension marketplace publishing | N/A |
Workflows marked with * are dual-purpose: they accept workflow_call for reuse by orchestration workflows and also run independently via their own triggers.
PR Validation Pipeline
The pr-validation.yml workflow serves as the primary quality gate for all pull requests. It runs 16 parallel jobs covering linting, security, and testing.
Jobs
| Job | Reusable Workflow | Validates |
|---|---|---|
| spell-check | spell-check.yml | Spelling across all files |
| markdown-lint | markdown-lint.yml | Markdown formatting rules |
| table-format | table-format.yml | Markdown table structure |
| psscriptanalyzer | ps-script-analyzer.yml | PowerShell code quality |
| yaml-lint | yaml-lint.yml | YAML syntax |
| pester-tests | pester-tests.yml | PowerShell unit tests |
| frontmatter-validation | frontmatter-validation.yml | AI artifact metadata |
| skill-validation | skill-validation.yml | Skill directory structure |
| link-lang-check | link-lang-check.yml | Link accessibility |
| markdown-link-check | markdown-link-check.yml | Broken links |
| dependency-pinning-check | dependency-pinning-scan.yml | Dependency pinning |
| npm-audit | Inline | npm dependency vulnerabilities |
| codeql | codeql-analysis.yml | Code security patterns |
| copyright-headers | copyright-headers.yml | Copyright header compliance |
| plugin-validation | plugin-validation.yml | Plugin and collection metadata |
| gitleaks-scan | gitleaks-scan.yml | Secret detection |
All jobs run in parallel with no dependencies, enabling fast feedback (typically under 3 minutes).
Main Branch Pipeline
The release-stable.yml workflow runs after merges to main, performing validation and release automation.
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.
Main Branch Jobs
| Job | Purpose | Dependencies |
|---|---|---|
| spell-check | Post-merge spelling validation | None |
| markdown-lint | Post-merge markdown validation | None |
| table-format | Post-merge table validation | None |
| dependency-pinning-scan | Security pinning check | None |
| gitleaks-scan | Secret detection scanning | None |
| pester-tests | PowerShell unit tests | None |
| release-please | Automated release management | All validation jobs |
| reset-prerelease | Reset pre-release tracking | release-please |
| extension-package-release | Build release VSIX | release-please (conditional) |
| plugin-package-release | Build release plugin packages | release-please (conditional) |
| generate-dependency-sbom | Generate dependency SBOM | release-please (conditional) |
| attest-and-upload | Sign and upload VSIX | release-please, extension-package-release, generate-dependency-sbom |
| upload-plugin-packages | Upload plugin packages | release-please, plugin-package-release |
| sbom-diff | Compare SBOM changes | release-please, generate-dependency-sbom |
| publish-release | Finalize GitHub Release | release-please, attest-and-upload, upload-plugin-packages, sbom-diff |
When 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.
Security Workflows
Weekly Security Maintenance
The weekly-security-maintenance.yml workflow runs every Sunday at 2AM UTC, providing scheduled security posture review.
| Job | Purpose |
|---|---|
| validate-pinning | Verify dependency pinning compliance |
| check-staleness | Detect outdated SHA references |
| codeql-analysis | Full CodeQL security scan |
| summary | Aggregate security status report |
Security Validation Tools
| Tool | Script | Checks |
|---|---|---|
| Dependency Pinning | Test-DependencyPinning.ps1 | Actions use SHA refs; npm uses exact versions |
| SHA Staleness | Test-SHAStaleness.ps1 | SHAs reference recent commits |
| npm Audit | npm audit | Known vulnerabilities in dependencies |
| CodeQL | GitHub native | Code patterns indicating security issues |
| Gitleaks | gitleaks | Secret detection in repository history |
| Dependency Review | GitHub native | Dependency vulnerability analysis |
Extension Publishing
The 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.
Publishing Jobs
| Job | Purpose | Workflow |
|---|---|---|
| normalize-version | Ensure version consistency | release-marketplace-stable.yml |
| validate-version | Enforce odd minor version for pre-release channel | release-marketplace-prerelease.yml |
| package (matrix) | Build one VSIX per collection using extension-package.yml | Both |
| publish (matrix) | Upload each VSIX to VS Code Marketplace via OIDC + vsce | Both |
Collection-Based Packaging
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.
| Collection | Maturity | Included In |
|---|---|---|
hve-core-all | Stable | Stable, PreRelease |
hve-core | Stable | Stable, PreRelease |
ado | Stable | Stable, PreRelease |
github | Stable | Stable, PreRelease |
project-planning | Stable | Stable, PreRelease |
coding-standards | Stable | Stable, PreRelease |
data-science | Stable | Stable, PreRelease |
security-planning | Stable | Stable, PreRelease |
design-thinking | Preview | Stable, PreRelease |
installer | Stable | Stable, PreRelease |
experimental | Experimental | PreRelease only |
Maturity filtering rules:
| Maturity Level | Build Inclusion |
|---|---|
| Deprecated | Always excluded |
| Experimental | Excluded from Stable channel builds |
| Preview | Included in both Stable and PreRelease channels |
| Stable | Included in all channel builds |
Version Channels
| Channel | Version Pattern | Marketplace |
|---|---|---|
| Stable | Even minor (1.2.0) | Main listing |
| Pre-release | Odd minor (1.3.0) | Pre-release flag |
npm Script Mapping
Workflows invoke validation through npm scripts defined in package.json:
| npm Script | Command | Used By |
|---|---|---|
lint:md | markdownlint-cli2 | markdown-lint.yml |
lint:md:fix | markdownlint-cli2 --fix | Local |
spell-check | cspell | spell-check.yml |
spell-check:fix | cspell --show-suggestions | Local |
lint:frontmatter | Validate-MarkdownFrontmatter.ps1 | frontmatter-validation.yml |
lint:md-links | Markdown-Link-Check.ps1 | markdown-link-check.yml |
lint:links | Invoke-LinkLanguageCheck.ps1 | link-lang-check.yml |
lint:yaml | Invoke-YamlLint.ps1 | yaml-lint.yml |
lint:ps | Invoke-PSScriptAnalyzer.ps1 | ps-script-analyzer.yml |
lint:collections-metadata | Validate-Collections.ps1 | plugin-validation.yml |
lint:marketplace | Validate-Marketplace.ps1 | plugin-validation.yml |
lint:version-consistency | Test-ActionVersionConsistency.ps1 | Local |
lint:all | Chains all linters | Local |
format:tables | markdown-table-formatter | table-format.yml |
test:ps | Invoke-PesterTests.ps1 | pester-tests.yml |
validate:skills | Validate-SkillStructure.ps1 | skill-validation.yml |
validate:copyright | Test-CopyrightHeaders.ps1 | copyright-headers.yml |
extension:prepare | Prepare-Extension.ps1 | extension-package.yml |
extension:prepare:prerelease | Prepare-Extension.ps1 -Channel PreRelease | extension-package.yml |
extension:package | Package-Extension.ps1 | extension-package.yml |
package:extension | Alias for extension:package | extension-package.yml |
extension:package:prerelease | Package-Extension.ps1 -PreRelease | extension-package.yml |
plugin:generate | Generate-Plugins.ps1 + post-process | plugin-package.yml |
plugin:validate | Alias for lint:collections-metadata | plugin-validation.yml |
Related Documentation
- Testing Architecture - PowerShell Pester test infrastructure
- Scripts README - Script organization and usage
🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.