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

> Learn to set up the CI/CD pipeline with GitHub Actions for HVE Core. Discover how to build reusable validation jobs and enforce security best practices for your automation.

- Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/microsoft/hve-core/blob/main/pr-validation.yml)** – Runs on every pull request to enforce the pre-merge gate
- **[`release-stable.yml`](https://github.com/microsoft/hve-core/blob/main/release-stable.yml)** – Executes on pushes to `main` to validate release candidates
- **[`weekly-security-maintenance.yml`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/spell-check.yml), [`.github/workflows/markdown-lint.yml`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/markdown-lint.yml), and [`.github/workflows/codeql-analysis.yml`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/pr-validation.yml) automatically triggers. This orchestrator runs nine distinct jobs that call reusable validators:

- Spell-check ([`spell-check.yml`](https://github.com/microsoft/hve-core/blob/main/spell-check.yml))
- Markdown lint ([`markdown-lint.yml`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/dependency-pinning-scan.yml) and [`.github/workflows/sha-staleness-check.yml`](https://github.com/microsoft/hve-core/blob/main/.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:

```yaml
permissions:
  contents: read

```

**Credential Isolation**  
Every checkout step explicitly disables credential persistence:

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

  with:
    persist-credentials: false

```

**Security Scanning Integration**  
CodeQL runs via [`.github/workflows/codeql-analysis.yml`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/spell-check.yml). Here is a complete example for adding ESLint validation:

```yaml
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`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/eslint-check.yml), then reference it from any orchestrator:

```yaml
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`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/pr-validation.yml), [`.github/workflows/release-stable.yml`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/release-stable.yml), [`.github/workflows/weekly-security-maintenance.yml`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.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`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/manual-ci.yml)) that uses the `workflow_dispatch` trigger to call the existing orchestrator:

```yaml
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`](https://github.com/microsoft/hve-core/blob/main/.github/dependabot.yml) to monitor GitHub Actions, npm, and Docker dependencies for updates. Additionally, the weekly security maintenance workflow ([`weekly-security-maintenance.yml`](https://github.com/microsoft/hve-core/blob/main/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.