How to Set Up the CI/CD Pipeline with GitHub Actions for HVE Core

HVE Core implements a modular, security-first CI/CD architecture using GitHub Actions orchestrator workflows that compose reusable validation jobs, enforcing SHA-pinned dependencies and minimal permissions across all automation.

The microsoft/hve-core repository demonstrates enterprise-grade continuous integration through a sophisticated workflow architecture. To set up the CI/CD pipeline with GitHub Actions for HVE Core, you adopt a two-tier pattern where top-level orchestrators trigger single-purpose reusable workflows, creating rigorous pre-merge gates and automated post-merge validation without code duplication.

Understanding the Orchestrator and Reusable Workflow Architecture

HVE Core separates concerns into orchestrator workflows and reusable workflows. This design allows the repository to maintain nine distinct validation jobs while avoiding repetitive YAML definitions.

Orchestrator workflows reside at the top level and respond to repository events. According to the source code, three primary orchestrators drive the entire pipeline:

• pr-validation.yml – Runs on every pull request to enforce the pre-merge gate
• release-stable.yml – Executes on pushes to main to validate release candidates
• weekly-security-maintenance.yml – Scheduled execution for security housekeeping

Reusable workflows use the workflow_call trigger to expose parameterized interfaces. Each performs one specific task—spell-checking, markdown linting, security scanning—and accepts inputs like soft-fail to control failure behavior. This pattern appears in .github/workflows/spell-check.yml, .github/workflows/markdown-lint.yml, and .github/workflows/codeql-analysis.yml.

Every workflow follows security defaults defined in the architecture: actions are SHA-pinned to 40-character commit hashes, persist-credentials is disabled during checkout, and each job requests only the minimal permissions it requires (typically contents: read).

The Three Core Pipeline Workflows

Pull Request Validation Orchestrator

When developers open or update a pull request, .github/workflows/pr-validation.yml automatically triggers. This orchestrator runs nine distinct jobs that call reusable validators:

• Spell-check (spell-check.yml)
• Markdown lint (markdown-lint.yml)
• Table format validation
• PowerShell lint
• Copyright header check
• YAML lint
• Front-matter validation
• Link checks
• Dependency-pinning scan

If any job reports a hard failure, the PR cannot merge. Each job uploads artifacts and posts annotations directly to the PR view, providing immediate feedback.

Release Validation Orchestrator

Every push to the main branch triggers .github/workflows/release-stable.yml. This workflow executes a focused subset of jobs—spell-check, markdown-lint, table-format, CodeQL analysis, and dependency-pinning—to provide the final quality gate before the automated release process publishes the VS Code extension and NPM package.

Weekly Security Maintenance

The scheduled workflow defined in .github/workflows/weekly-security-maintenance.yml runs every Sunday without requiring code changes. It performs SHA-staleness checks, dependency-pinning scans, CodeQL analysis, and posts a summary markdown report to maintain the repository's security posture during inactive development periods.

Security-First Implementation Details

The pipeline enforces strict supply-chain security through several mechanisms implemented in the workflow files.

SHA Pinning Validation
The .github/workflows/dependency-pinning-scan.yml and .github/workflows/sha-staleness-check.yml workflows verify that every action reference uses a full 40-character commit SHA rather than mutable tags. The helper script scripts/security/Update-ActionSHAPinning.ps1 automates the process of bumping these pins when new versions release.

Minimal Permissions
Each reusable workflow declares explicit permissions at the job level. For example, the spell-check workflow requests only:

permissions:
  contents: read

Credential Isolation
Every checkout step explicitly disables credential persistence:

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v4.2.2

  with:
    persist-credentials: false

Security Scanning Integration
CodeQL runs via .github/workflows/codeql-analysis.yml and uploads SARIF results to the Security tab. Gitleaks scans for accidentally committed secrets. Both are wired into the orchestrators automatically.

Deploying the Pipeline to Your Repository

To replicate the HVE Core CI/CD setup in a fork or new repository:

1. Copy the workflow directory – Clone the .github/workflows/ folder from microsoft/hve-core into your repository root.

2. Preserve SHA pins – Verify that the 40-character SHA pins in every uses: statement match the upstream source. Do not replace these with version tags.

3. Enable Actions – Activate GitHub Actions in your repository settings. No additional configuration is required—the workflows use repository-dispatch triggers by default.

4. Configure Dependabot – Include the .github/dependabot.yml file to automatically receive updates for pinned GitHub Actions, npm packages, and Docker images.

5. Validate setup – Open a test pull request to verify that pr-validation.yml triggers correctly and all reusable workflows execute without authentication errors.

Creating Custom Reusable Workflows

When extending the pipeline, follow the established skeleton from .github/workflows/spell-check.yml. Here is a complete example for adding ESLint validation:

name: ESLint Check
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: "20"
      soft-fail:
        type: boolean
        default: false

permissions:
  contents: read

jobs:
  eslint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v4.2.2

        with:
          persist-credentials: false
      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0

        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci
      - run: npx eslint .
        continue-on-error: ${{ inputs.soft-fail }}
      - name: Upload ESLint report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: eslint-results
          path: eslint-report.json

Save this as .github/workflows/eslint-check.yml, then reference it from any orchestrator:

eslint:
  uses: ./.github/workflows/eslint-check.yml
  with:
    node-version: "20"
    soft-fail: true

Summary

• HVE Core uses a two-tier architecture where orchestrator workflows (.github/workflows/pr-validation.yml, .github/workflows/release-stable.yml, .github/workflows/weekly-security-maintenance.yml) trigger reusable validation jobs via workflow_call.
• Security defaults are mandatory: all actions use SHA-pinned commits, credentials do not persist between steps, and jobs request minimal permissions.
• The pipeline runs automatically on pull requests, pushes to main, and weekly schedules without requiring manual intervention.
• Deployment requires copying the .github/workflows/ directory and preserving SHA pins, optionally enabling Dependabot updates via .github/dependabot.yml.
• Extending the pipeline follows a consistent pattern: create a new file with workflow_call inputs, implement the validation logic, and add a job reference to the appropriate orchestrator.

Frequently Asked Questions

What is the difference between orchestrator and reusable workflows in HVE Core?

Orchestrator workflows are the entry points triggered by GitHub events (PRs, pushes, schedules). They define the execution order and call other workflows. Reusable workflows are single-purpose utilities declared with workflow_call that perform specific tasks like spell-checking or security scanning. According to the source code in .github/workflows/README.md, this separation allows the nine validation jobs to be maintained independently while being composed differently for PR validation versus release checks.

How does HVE Core enforce supply-chain security in GitHub Actions?

The pipeline enforces SHA pinning through .github/workflows/dependency-pinning-scan.yml, which verifies that every action uses a 40-character commit SHA rather than mutable tags. Additionally, .github/workflows/sha-staleness-check.yml detects outdated pins during the weekly maintenance window. Every checkout step explicitly sets persist-credentials: false, and the helper script scripts/security/Update-ActionSHAPinning.ps1 automates pin updates when new action versions release.

Can I trigger the HVE Core CI/CD pipeline manually instead of on automated events?

Yes. Create a new workflow file (for example, .github/workflows/manual-ci.yml) that uses the workflow_dispatch trigger to call the existing orchestrator:

name: Run Full CI Manually
on:
  workflow_dispatch:

jobs:
  full-ci:
    uses: ./.github/workflows/pr-validation.yml

This configuration adds a "Run workflow" button to the Actions UI, allowing maintainers to execute the full validation suite on demand without opening a pull request.

How are the pinned action versions kept up to date?

The repository uses Dependabot configured in .github/dependabot.yml to monitor GitHub Actions, npm, and Docker dependencies for updates. Additionally, the weekly security maintenance workflow (weekly-security-maintenance.yml) runs the SHA-staleness check to flag actions that need version bumps. While Dependabot proposes updates via pull requests, the Update-ActionSHAPinning.ps1 script in scripts/security/ can manually refresh pins to specific commits when automated updates are insufficient.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}