Contributing to Opsmith¶
Thanks for helping. This page gets you from a fresh clone to a change that passes CI.
AGENTS.md is the full contributor guide (for people and for AI coding agents):
the repository map, the invariants that must never be broken, and the conventions the code
follows. Read its Invariants section before changing anything in the review gate, the
executor, the LLM gateway or the API.
Set up¶
You need Python 3.12+, uv and git. Docker is optional: without it the tests that start real containers are skipped.
git clone https://github.com/deadboyccc/Opsmith.git && cd Opsmith
uv sync --all-extras
uv run opsmith demo --dir /tmp/opsmith-demo # the whole loop, offline; ends with "verified"
No local Python? make docker-test runs the same checks inside a container.
docs/development/testing.md explains the test suite, including
how to run it on PostgreSQL, with real sandbox containers, and against a live model. Internals
are in docs/development/architecture.md.
Make a change¶
uv run pytest tests/test_<area>.py -q # iterate on the area you are touching
make fmt # auto-fix lint and formatting
make check # ruff, format, mypy, tests + coverage floor, docs check
make audit # known vulnerabilities in the locked dependencies
What reviewers look for:
- A test for the behaviour, including the failure path. For anything that guards safety
(approval, sandbox, redaction, tenancy, roles) add a test that tries the bad path and shows it
is blocked.
tests/test_hardening.pyhas many examples. - Tests stay offline. Use
httpx.MockTransport, also under the real Anthropic SDK; never the network. - No silent drops. A failure must end as a retry, a dead job with a notification, a task back in review with a report, or a finding marked suppressed with a reason.
- Docs move with the code. Pages for people using Opsmith are under
docs/guide/; pages for people changing it are underdocs/development/. Update the one your change affects,ARCHITECTURE_DECISIONS.mdfor a design change,docs/DECISIONS.mdfor a choice between workable options, andCHANGELOG.mdunder Unreleased in the same commit.make docschecks every link and fails when a setting, endpoint, state or command the code offers is not documented. The pages are also the documentation site;make sitebuilds it, and a new page needs an entry innavinmkdocs.yml.
Commits and pull requests¶
- Imperative, scoped subject lines:
executor: block secrets on added lines only. - One topic per pull request. Say what changed, why, the risk, and how you verified it.
- Never commit generated data (
data/,opsmith-demo/,*.db) or real credentials. Configuration takes references such asenv:GITHUB_TOKEN, never values.
Reporting problems¶
- Bugs and ideas: open an issue with what you did, what happened and what you expected.
- Security problems: open an issue with the Security problem form. See SECURITY.md.
By contributing you agree that your contribution is licensed under the MIT License.