Skip to content

ci.md

Latest commit

 

History

History
160 lines (106 loc) · 3.46 KB

ci.md

File metadata and controls

160 lines (106 loc) · 3.46 KB
Raw

Continuous integration

The repository uses GitHub Actions to validate its configuration, documentation, scripts, and security checks automatically.

The workflow is defined in:

.github/workflows/ci.yml

Triggers

The workflow runs automatically:

  • on pushes to the main branch;
  • on pull requests;
  • when started manually through workflow_dispatch.

Permissions

The workflow uses read-only repository permissions:

permissions:
  contents: read

No write access is required for repository quality checks.

Repository quality job

The workflow contains a quality job running on the latest Ubuntu GitHub-hosted runner.

Its purpose is to reproduce the repository-wide checks normally executed locally through pre-commit.

GitHub Actions repository quality job

The workflow installs the tools required by hooks declared with:

language: system

These tools include:

  • markdownlint-cli2;
  • lychee;
  • editorconfig-checker;
  • actionlint.

Hooks provided directly by remote pre-commit repositories, including Gitleaks, ShellCheck, and the standard pre-commit hooks, are installed automatically by pre-commit.

Validation command

The complete repository is validated with:

pre-commit run --all-files --show-diff-on-failure

This keeps local and continuous integration checks aligned around the same configuration:

.pre-commit-config.yaml

Checks performed

The current workflow validates:

  • trailing whitespace;
  • missing final newlines;
  • YAML syntax;
  • accidentally added large files;
  • unresolved merge conflict markers;
  • private keys;
  • hardcoded secrets with Gitleaks;
  • Markdown formatting;
  • documentation links;
  • EditorConfig compliance;
  • GitHub Actions workflow syntax;
  • shell script linting with ShellCheck (scripts/*.sh, install.sh).

macOS workflow

An additional macOS workflow validates platform-specific behavior:

  • .github/workflows/ci-macos.yml runs the test suite, checks the setup CLI contract (--dry-run), installs the full Homebrew profile, applies setup once, and runs the verification and hardening checks (scripts/verify.sh).

Pre-commit cache

GitHub Actions caches pre-commit environments under:

~/.cache/pre-commit

The cache key includes the operating system and a hash of:

.pre-commit-config.yaml

Changing the pre-commit configuration therefore creates a new cache automatically.

Validate locally

Validate the workflow structure without executing it:

actionlint .github/workflows/ci.yml

Run the same repository checks locally:

pre-commit run --all-files

Run the quality job locally with Act:

act pull_request \
  --job quality \
  --container-architecture linux/amd64 \
  -P ubuntu-latest=catthehacker/ubuntu:act-latest \
  --pull=false

Act provides useful local feedback but does not reproduce GitHub-hosted runners perfectly.

A successful run on GitHub Actions remains the final validation.

Inspect GitHub Actions runs

List recent workflow executions:

gh run list \
  --workflow CI \
  --limit 5

Inspect the latest failed workflow logs:

gh run view --log-failed

Related documentation

← Docs index · Project README