## Description
Makes PR workflow runs more selective by routing docs-only changes to
docs validation instead of the full CI workflow, while preserving
workflow validation and existing code/e2e/release gates for applicable
changes.
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)
## Changes Made
- Added `pull_request.paths-ignore` to `.github/workflows/ci.yml` so
docs/wiki/markdown-only PRs do not queue the general CI workflow.
- Removed `.github/workflows/ci.yml` from the CI internal `code` path
filter so CI-only workflow edits can run workflow validation without
forcing Python/Rust code jobs.
- Added a docs PR validation job to `.github/workflows/docs.yml` for
`docs/**`, `wiki/**`, `mkdocs.yml`, and docs workflow changes.
- Reduced default docs workflow token permissions to `contents: read`,
with `contents: write` scoped only to the deploy job.
- Added docs workflow dry-runs to `scripts/validate-workflows.sh` so
local/CI workflow validation covers the new PR and manual docs paths.
## Testing
- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ actionlint .github/workflows/ci.yml .github/workflows/docs.yml
# no output
$ act pull_request -W .github/workflows/docs.yml -n
*DRYRUN* [Deploy Documentation/validate] 🏁 Job succeeded
$ act workflow_dispatch -W .github/workflows/docs.yml -n
*DRYRUN* [Deploy Documentation/deploy] 🏁 Job succeeded
$ act pull_request -W .github/workflows/ci.yml -n
*DRYRUN* [CI/changes] 🏁 Job succeeded
*DRYRUN* [CI/commitlint] 🏁 Job succeeded
$ python -m mkdocs build
INFO - Documentation built in 1.28 seconds
$ bash scripts/validate-workflows.sh
# completed successfully; act dry-runs passed. Some unsupported runner-platform matrix entries are skipped by local act, as before.
$ git diff --check
# no output
```
## Real Behavior Proof
- Environment: Windows local checkout, branch `smart-pr-runs`, `act`
0.2.87, temporary local `actionlint` installed via `go install`.
- Exact command / steps: Ran `actionlint` against changed workflows,
`act` dry-runs for docs PR/manual paths and CI PR path, actual `python
-m mkdocs build`, full `scripts/validate-workflows.sh`, and `git diff
--check`.
- Observed result: Changed workflows lint cleanly; docs PR and manual
docs workflow paths dry-run successfully; CI PR dry-run still covers
`changes` and `commitlint`; MkDocs builds; repository workflow
validation script completes with the new docs dry-runs included.
- Not tested: Full non-dry-run GitHub Actions execution on hosted
runners before PR creation.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable
## Screenshots (if applicable)
N/A.
## Additional Notes
- No issue is linked because this PR was not opened for a specific
tracked issue.
- `mkdocs build` reports existing docs/nav warnings but exits
successfully; strict mode currently fails on existing warnings, so the
PR validation uses the deploy-compatible non-strict build.
- Python unit/lint/type checks are not applicable to this workflow-only
change.
* ci: speed up GitHub Actions - path filters, caching, timeouts, version upgrades
Performance improvements:
- init-e2e.yml, wrap-e2e.yml: add path filters so e2e Docker builds only run when
e2e-related files change (saves ~10 min per irrelevant PR push)
- init-e2e.yml, wrap-e2e.yml: add concurrency groups to cancel superseded PR runs
- ci.yml: add pip caching to lint and build jobs
- ci.yml: cache actionlint + act binaries in workflow-validation (skip curl on hits)
- eval.yml: add pip caching to smoke-test and weekly-suite jobs
- docs.yml: add pip caching for mkdocs-material install
- rust.yml: replace cargo install --locked cargo-audit/deny with taiki-e/install-action
(prebuilt binaries; saves 2-5 min per audit run)
Bug fixes:
- docker.yml: fix actions/checkout@v6 -> @v4 (v6 does not exist; would break all
Docker builds on every release/PR touching docker paths)
Version upgrades:
- wagoid/commitlint-github-action: @v5 -> @v6
- devcontainers.yml: docker/setup-buildx-action@v3 -> @v4 (align with docker.yml)
Safety improvements:
- ci.yml: add timeout-minutes to all 13 jobs (changes, lint, build-wheel,
prefetch-model, test x4, test-extras, test-agno, commitlint, build,
workflow-validation, docker-native-e2e, windows-native-wrapper, macos-native-wrapper)
- docker.yml: add timeout-minutes to docker-build (75m), docker-manifest (20m),
promote-latest (10m)
- eval.yml: add timeout-minutes to smoke-test (30m); bump weekly-suite 60->90m
- rust.yml: add timeout-minutes to test (30m), wheels (45m), audit (20m)
Observed wall-clock impact on recent PRs:
- Init E2E and Wrap E2E were running on every single PR push regardless of content
- CI workflow was taking 12-17 min; path filters reduce unnecessary e2e runs to 0
* fix(ci): bust actionlint+act cache when workflow file changes
Static cache key 'ci-tools-actionlint-act-v1' never invalidated on
tool version updates. Switched to hashFiles('.github/workflows/ci.yml')
so the cache busts automatically whenever the download scripts are
updated to point at a newer release.
Flagged by adversarial review (Architecture + Testing/Reliability personas).
* fix(ci): add missing Dockerfile COPY paths to e2e path filters
e2e/init/Dockerfile and e2e/wrap/Dockerfile COPY files not covered
by the initial path filter set:
init-e2e: Cargo.toml, Cargo.lock, rust-toolchain.toml, uv.lock,
.claude-plugin, .github/plugin/**, plugins/headroom-agent-hooks/**
wrap-e2e: Cargo.toml, Cargo.lock, rust-toolchain.toml, uv.lock,
sdk/typescript/**, plugins/openclaw/**
Without these, a Rust toolchain bump or SDK change on a PR would
skip the e2e gate entirely, only catching it on the merge to main.
Flagged by adversarial review (Domain/Correctness persona).
* fix(devcontainer): upgrade uv to >=0.7.0 to parse uv.lock revision=3
* fix(devcontainer): set UV_SKIP_WHEEL_FILENAME_CHECK=1 in post-create.sh for gitpython wheel
* ci: bump actions/checkout and actions/setup-node to v5 (Node.js 20 EOL Jun 16)
* fix(devcontainer): export UV_SKIP_WHEEL_FILENAME_CHECK so uv run also skips wheel check
* ci: bump all GitHub Actions to latest versions (Node.js 24)
* fix(test): accept release-please-action v4 or v5 in workflow assertion
* fix(format): ruff format test_release_workflows.py
- Add mkdocs.yml with Material theme (indigo, professional)
- Add docs/index.md landing page with quick install
- Add GitHub Actions workflow for auto-deployment
- Remove old docs/README.md (replaced by index.md)
