How to use our CI pipeline and keep builds fast

I have spent too much time waiting for a CI pipeline to finish, only to realize it failed on a simple formatting error twenty minutes later. It is frustrating when expensive tests run on code that is not even ready yet.

I want to show you how our CI handles this. We use smart scoping to skip jobs that do not need to run and a fail-fast order to catch errors early. This keeps the feedback loop short and saves resources.

What You’ll Need

To work with this pipeline effectively, you should have these tools and environments ready:

• pnpm: Used for running local checks and tests.
• Linux/Windows/macOS Runners: The pipeline uses blacksmith-4vcpu-ubuntu-2404, blacksmith-4vcpu-windows-2025, macos-latest, and ubuntu-latest.
• Python: Required if you run the scripts/analyze_code_files.py script manually.

Quick Start

You can avoid CI failures by running the same checks locally before you push. I recommend these four commands to verify your changes:

pnpm check          # types + lint + format
pnpm test           # vitest tests
pnpm check:docs     # docs format + lint + broken links
pnpm release:check  # validate npm pack

Our CI follows a specific order so cheap checks fail before expensive ones:

1. Phase 1: docs-scope, code-analysis, and check run in parallel. These take about 1-2 minutes.
2. Phase 2: build-artifacts runs only if Phase 1 passes.
3. Phase 3: Heavy tests like checks, checks-windows, macos, and android run after the build is ready.

Code Analysis and Limits

We use a code-analysis job to keep the codebase clean. It runs a script on pull requests to check for file size. If a file grows past 1000 lines, the build fails.

This check is “delta-only,” meaning it only looks at files you changed in your PR. If you use the --strict flag, any violation will block all downstream jobs. I find this helpful for catching bloated files before the expensive native tests start.

The script ignores these directories:

• node_modules, dist, vendor, .git
• coverage, Swabble, skills, .pi

Troubleshooting

CI is skipping my tests

If you only changed files in the docs folder, the docs-scope job will detect this and skip the native builds and Node tests. This is expected behavior to save time.

Build failed on code-analysis

If your PR fails the code-analysis job, check if any of your modified files exceed 1000 lines. You will need to refactor or split the file to pass. This job is skipped on pushes to main so merges are not blocked.

Secrets detected

The secrets job runs on every push. If it fails, check your commit for leaked API keys or credentials. This job runs always, regardless of what files changed.

If you have more questions about the setup, ask the AI Setup Assistant.

What’s Next

• Testing Guide
• Deployment Workflow
• Contributing Guidelines
• Runner Configuration