Skip to content

CI / CD

VBAlidator ships a complete release pipeline. Every workflow lives in .github/workflows/ and is wired up so any push to main produces:

  • a fresh PyPI release (when commits warrant a bump),
  • a multi-arch Docker image on GHCR,
  • updated GitHub Pages docs (this site),
  • a security report.

Open the GitHub Actions tab to see them live.

Workflows

Workflow Trigger Purpose
ci.yml push, PR Lint (ruff), 15-job test matrix (3 OS × 5 Py), CLI smoke, rule-doc sync gate
release.yml push to main, manual python-semantic-release → tag → GitHub Release → PyPI Trusted Publisher; nightly TestPyPI dev-release
docker.yml push, tag, PR Multi-arch (amd64, arm64) image build, Trivy scan (HIGH/CRITICAL fail), GHCR push + image smoke test
security.yml push, PR, weekly pip-audit, bandit, CodeQL
pr-quality.yml PR Conventional-Commit title + commit-message lint, PR-size labelling
docs.yml push, PR MkDocs Material build → GitHub Pages
roundtrip.yml nightly, manual Windows + Office VBE round-trip; auto-files an issue on disagreement
nightly-coverage.yml nightly Per-project Awesome-VBA score snapshot for drift detection

Conventional Commits

PR titles and merge commits must follow Conventional Commits. The pr-quality.yml workflow enforces this on every PR.

feat(precompiler): add VBA350 rule for `End Function` placement
fix(parser): handle nested With blocks
docs(rules): clarify VBA300 fix-hint
chore(deps): bump pytest to 9.0.3

The mapping to semver bumps is:

Type Bump
feat minor
fix, perf, refactor patch
BREAKING CHANGE: footer major

Configured in pyproject.toml → [tool.semantic_release].

Release lifecycle

  1. Merge a feat: / fix: PR into main.
  2. release.yml runs semantic-release version:
    • Bumps pyproject.toml and src/__init__.py __version__.
    • Updates CHANGELOG.md.
    • Creates an annotated git tag vX.Y.Z.
    • Publishes a GitHub Release with the autogenerated notes.
  3. Build artifacts (wheel + sdist) are uploaded.
  4. The publish-pypi job pushes them to PyPI via OIDC Trusted Publisher — no API tokens.
  5. The docker.yml workflow rebuilds the image on the new tag and pushes ghcr.io/twobeass/vbalidator:X.Y.Z and :latest.
  6. docs.yml redeploys this site.

End-to-end time: ~6–8 minutes from merge to PyPI/GHCR/docs.

Configure main with:

  • Required status checks: Lint (ruff), Test (Py3.12 on ubuntu-latest), CLI smoke test, Rule docs in sync, Conventional Commits, pip-audit, bandit, CodeQL.
  • Required reviewers: ≥1 from the CODEOWNERS file.
  • Dismiss stale reviews on new commits.
  • Require signed commits.

Local pre-commit

Hooks live in .pre-commit-config.yaml and mirror the CI lint step:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Secrets / settings required

Secret / setting Where Purpose
PyPI Trusted Publisher pypi.org/manage/account/publishing/ Maps the vbalidator project to the release.yml workflow on this repo. No token needed.
TestPyPI Trusted Publisher test.pypi.org Same, for the dev-release flow.
id-token: write permission repo Settings → Actions OIDC for PyPI. Already declared in the workflow.
GitHub Pages source repo Settings → Pages Set to "GitHub Actions".
Office on a self-hosted Windows runner roundtrip.yml Optional — enables nightly VBE round-trip cross-checks.