langship.sh/CONTRIBUTING.md

Contributing to Langship

Thanks for your interest. This guide covers the dev setup, what to run before opening a PR, and the conventions we follow.

By contributing, you agree your contributions are licensed under the Apache License 2.0 (the project's license). No CLA or DCO sign-off is required.

Code of conduct

Participation is governed by CODE_OF_CONDUCT.md. Report concerns to khush@lyzr.ai.

Repo layout

Path	What
cmd/flow/	the flow server binary (API + Restate worker entry point)
pkg/api/	REST + SSE handlers
pkg/orchestrator/, pkg/engine/	DAG walk, execution context, events
pkg/executors/	node implementations (Build, Push, SAST, Approval, Promote, Deploy, …)
pkg/awsdeploy/	AWS Bedrock AgentCore adapter (STS, ECR, IAM, control-plane SigV4)
pkg/storage/	Mongo-backed stores (pipelines, runs, agents, credentials, environments)
pkg/secrets/	AES-GCM seal/open keyed off FLOW_SECRET_KEY
web/	Next.js UI (static export)
langship-cli/	the langship Python CLI

Dev environment

Backing services (Mongo, Restate, BuildKit, MinIO, registry) come up via docker-compose; the Go API runs on the host. See the Quickstart and Dev (hot reload) sections in the README for the exact commands. In short:

make services        # docker-compose: mongo, restate, buildkitd, registry, minio
make watch           # Go API with air (rebuilds on .go change)   — or `make serve` for a stable binary
cd web && pnpm dev   # Next dev server, /api proxies to :8090

Set FLOW_SECRET_KEY in your environment before working on anything that touches credentials/environments — the API refuses credential writes without it.

CLI:

pip install -e ./langship-cli
langship login --api-url http://localhost:8090

Before you open a PR

• Go: go build ./... and go test ./... must pass. Run gofmt/go vet on changed files.
• Web: cd web && pnpm tsc --noEmit must pass (and pnpm build if you changed anything that affects the static export).
• CLI: pip install -e ./langship-cli && langship --help should work; smoke-test any command you touched against a local server.
• Keep changes focused — one logical change per PR.
• Update the README / CLI README / aude.md if you changed behavior they describe.

Conventions

• Commits: imperative subject, ≤ ~72 chars (feat:/fix:/refactor: prefixes are welcome but not required). Squash noise before pushing.
• Branches: main is the trunk; branch off it. Don't push directly to main — open a PR.
• Code style: match the surrounding code. Comments explain why, not what. Executors emit __<node> summary objects on output items; follow that pattern.
• Errors: wrap with context (fmt.Errorf("deploy: %w", err)); the API layer maps storage.ErrNotFound → 404 and storage.ErrAlreadyExists → 409.
• No secrets in code or commits. Anything sensitive goes through pkg/secrets and is never returned by the API.

Adding a node executor

1. Implement executors.NodeExecutor in pkg/executors/<name>.go. Read the trigger payload via firstItem(inputs) for agentId / environment / fromBranch. Emit each input item with a __<name> summary attached.
2. Register it in pkg/executors/registry.go (pass any stores it needs via RegistryDeps).
3. Add a catalog entry in web/lib/node-catalog.ts and a <Name>Form in web/components/canvas/node-form.tsx.
4. If it pauses (like Approval), special-case it in pkg/orchestrator/walk.go so it isn't wrapped in restate.Run (it calls Restate context methods directly).

Reporting bugs

Open a GitHub issue with: what you did, what you expected, what happened, and the relevant logs (flow server output + the run's node logs from langship runs logs <id> or /api/executions/{id}/logs/{node}).

Security

Vulnerabilities go to khush@lyzr.ai privately — see SECURITY.md. Do not open a public issue.