Operations

How CI/CD, deploys, and secrets are configured for bitpilot.

CI Pipeline

A single workflow at .github/workflows/ci.yml runs on every push and every pull request. It replaces the previous test.yml.

Jobs

Job	Runs On	Purpose
`lint`	ubuntu, Python 3.12	`ruff check .`
`typecheck`	ubuntu, Python 3.12	`mypy python/bitpilot`
`test`	ubuntu, Python 3.10/3.11/3.12	`pytest` with `[dev,agent,lightning]` extras
`docs`	ubuntu, Python 3.12	Generate metadata, build site docs, run contract tests
`deploy-preview`	ubuntu	Netlify preview deploy (PRs only, after all checks pass)
`deploy-production`	ubuntu	Netlify production deploy (main branch only, after all checks pass)

Concurrency

Pushes to the same branch cancel in-progress runs:


concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Netlify Deploy

Required GitHub Secrets

Set these in Settings > Secrets and variables > Actions:

Secret	Description	Where to find it
`NETLIFY_AUTH_TOKEN`	Personal access token	Netlify User Settings > Applications > Personal access tokens
`NETLIFY_SITE_ID`	Site identifier	Netlify site dashboard > Site configuration > General > Site ID

The current site ID is b3067f9b-3399-4618-b99d-eef500f53c6b (from .netlify/state.json).

Publish Directory

The Netlify publish directory is site/. The CI pipeline builds site/docs/ from docs/.md and copies docs/api/.json into site/docs/api/ before deploying.

Deploy Flow


Push to main
  -> lint + typecheck + test + docs (parallel)
  -> all pass
  -> deploy-production: build site docs, netlify deploy --prod


Open PR
  -> lint + typecheck + test + docs (parallel)
  -> all pass
  -> deploy-preview: build site docs, netlify deploy (preview URL)

Preview URLs

PR preview deploys produce a unique URL visible in the GitHub Actions summary and as a PR comment (via the nwtgck/actions-netlify action).

Production URL

The production site is deployed to the URL configured in Netlify (e.g. bitpilot.space or the default *.netlify.app subdomain).

Rollback

To roll back a production deploy:

Revert the commit and push to main — CI redeploys the previous state.
Or use the Netlify dashboard: go to Deploys, find a previous successful deploy, and click Publish deploy.

Docs Metadata Drift

If you add a new public symbol to bitpilot.__all__ or a new CLI command, CI will fail at the docs job with a drift error. To fix:


python scripts/generate_docs_metadata.py
git add docs/api/
git commit -m "Update docs metadata"

Local Development


pip install -e ".[dev,agent,lightning]"
python scripts/generate_docs_metadata.py
python scripts/build_site_docs.py
python -m pytest tests/test_docs_contract.py -v

Open site/index.html in a browser to preview the homepage. Open site/docs/index.html for the docs.