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

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.
Register it in pkg/executors/registry.go (pass any stores it needs via RegistryDeps).
Add a catalog entry in web/lib/node-catalog.ts and a <Name>Form in web/components/canvas/node-form.tsx.
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.

4.0 KiB Raw Permalink Blame History