How to contribute
Set up a development environment, find something to work on and send a change.
shpyrd is developed in the open at github.com/shpyrd-io/shpyrd under the MPL-2.0 license. The exception is ee/, the enterprise features: its source is public under the shpyrd Enterprise License, and only the shpyrd team changes it for now, so pull requests there are not accepted. Issues, ideas and pull requests are welcome everywhere else.
Where to start
- Try it and report. Follow Getting started, or install it on your machine, and open an issue for anything confusing, slow or broken. UX feedback is as valuable as code at this stage.
- Pick an issue. The issue tracker has bugs and roadmap items. Comment on one before starting so work is not duplicated.
- Propose a change. Small fixes go straight to a pull request. Anything that changes behaviour or architecture starts as an issue describing the problem and the shape of the change first.
- Talk. Questions and discussions happen on Discord; the code of conduct applies everywhere.
Development environment
Docker, Go 1.27 and Node.js 24, the version in .nvmrc (nvm use; for the applications, the design library and the website). Run npm install once at the repository root: the applications, design/ui and content/ are one npm workspace. Another Node brings another npm, which writes package-lock.json in another order; npm warns when the version is not 24.
git clone https://github.com/shpyrd-io/shpyrd && cd shpyrdmake cli # ./bin/shpyrd and ./bin/shpyrd-ctlmake dev-cluster # kind cluster with everything except the shpyrd servermake dev-deploy # build the server image, load it into kind, apply the shpyrd componentmake dev-deploy again after changes to the server or the controller.
The dashboard is two applications the server embeds: apps/workspace (a workspace's dashboard) and apps/console (the platform's). Each runs on its own with hot reload - npm run dev against a shpyrd server (SHPYRD_DEV_API names it; see the application's next.config.ts), or npm run design against sample data, with no server at all:
npm --prefix apps/workspace run design # http://localhost:4325npm --prefix apps/console run design # http://localhost:4326How an application is made, and how a design session runs, are in apps/AGENTS.md and design/DESIGN_FOR_AGENT.md.
Useful targets:
make test vet # Go tests, the applications' tests, and go vetmake generate # regenerate the App CRD and deepcopy code after editing api/make ui # build the applications the server embedsnpm --prefix apps/workspace run lint && npm --prefix apps/workspace run test./bin/shpyrd-ctl cluster init --only shpyrd --set SHPYRD_SERVER_IMAGE=shpyrd-server:dev # re-apply one componentManifests under deploy/ are embedded in the binaries: rebuild the CLI after editing them.
Conventions
- Commit messages follow Conventional Commits (
feat:,fix:,docs:,chore:) and carry a DCO sign-off (git commit -s). - Go code is
gofmted andgo vetclean; the applications,design/uiand the website areoxlintclean, type-checked and tested (npm run lint,npm run typecheck,npm run testin each). - Tests live next to the code:
internal/controller(reconciler with a fake client),pkg/api(handlers with fake clients and an httptest Prometheus),pkg/install(every component renders offline). - User-facing names follow the concepts: projects, processes, instances, builds, releases, config vars.
Documentation
These pages live in this repository. Each is an MDX file (Markdown with a few named editorial blocks) under content/docs/, and the menu beside them is content/docs/index.mdx; the site that draws them is apps/website (Next, made of design/ui). To preview:
make website-dev # http://localhost:4324/docs/getting-startedA saved page shows at once. npm --prefix content run test checks that every page is in the menu and every entry of the menu has a page. Besides Markdown, a page can use a few tags: callout, quick-links, chat with message for a conversation with an agent, and agent-setup for the tabs that show how to add shpyrd to each agent.
Support the project
shpyrd is free and open source. If it saves you time, you can support its development with a donation: donate.stripe.com/9B63cxfbwg8H31OgPX2ZO01. Thank you.