Skip to main content

Continuous Integration

Summary​

The Documentation CI workflow applies repeatable quality gates to documentation changes before merge and retains the validated static build for inspection.

Audience​

  • Documentation contributors
  • Documentation reviewers
  • Repository maintainers
  • Developers maintaining validation tooling

Reference Content​

CI triggers​

The workflow runs for:

  • Pull requests targeting main
  • Pushes to main
  • Manual workflow_dispatch runs

No path filter is applied. This prevents validation from being skipped when workflow, dependency, configuration, source, documentation, or validation-tooling changes affect portal quality.

Validation stages​

The Documentation quality gate job runs on ubuntu-latest with a 20-minute timeout:

  1. Dependency installation — npm ci
  2. Validator tests — npm test
  3. Documentation governance validation — npm run docs:validate
  4. TypeScript validation — npm run typecheck
  5. Docusaurus production build — npm run build
  6. Whitespace validation — git diff --check plus the applicable pull-request or push commit range
  7. Artifact upload — stores the validated build/ directory only after prior stages pass

The commands remain separate so GitHub identifies the failing quality stage without repeating the production build.

Build artifact​

Successful runs upload build/ as the hrsuit-docs-build workflow artifact with seven-day retention. Missing build output fails the artifact step. The artifact is retained for review only and is not published or deployed.

Failure handling​

A non-zero command exit stops the job and blocks the quality gate. Contributors should open the failing step, reproduce the command locally, correct the underlying issue, and rerun all checks before requesting approval.

Local reproduction​

Run the locked installation, validator tests, and composite local quality gate:

npm ci
npm test
npm run docs:check

Required-check recommendation​

Configure GitHub repository settings manually to:

  • Protect main.
  • Require a pull request before merging.
  • Require the Documentation quality gate status check.
  • Require branches to be up to date before merging.
  • Block merges when the required check fails.
  • Prevent direct pushes where appropriate for repository maintainers and contributors.

Branch protection is an administrative repository setting and is not configured by this workflow or by repository scripts.

CI versus deployment​

Continuous integration validates source content and produces a review artifact. Deployment publishes content to a hosting environment. This workflow performs no publishing, deployment, environment creation, DNS operation, or production credential use.

Security and permission model​

The workflow grants the GitHub token read-only repository-content permission. Checkout credentials are not persisted. It references no repository secrets and performs no authenticated write operation. Concurrency cancels older runs only for the same pull request or branch, and each job has a finite timeout.

Official GitHub actions are used for checkout, Node setup with lockfile-based npm caching, and artifact upload. Dependency installation uses npm ci so the workflow consumes the committed lockfile without updating it.

Known dependency risk​

The current dependency tree reports existing transitive npm audit findings. This workflow does not perform automatic or unrelated dependency upgrades. Remediation requires a separately reviewed dependency-maintenance change.

See Also​

Keywords​

  • Documentation CI
  • GitHub Actions
  • Required status check

Revision Information​

  • Last reviewed: 2026-07-14
  • Owner: documentation-team
  • Status: Approved