Contribution Workflow#

Overview#

Langfuse accepts contributions via GitHub pull requests to the main application repo, the docs repo, and the SDKs (Python, JS). The process from idea to merged PR has four sequential gates: issue discussion → code ready → CLA signed → CI passing. 1

Good starting points: the good first issue label and the Ideas discussions board. Maintainers are available on Discord for questions. 2

Step 1 — Open an Issue First#

Before writing code, open an issue to discuss the proposed change. PRs submitted without prior issue discussion may be rejected. 3

Step 2 — CLA Requirement#

Every contributor must sign the Contributor License Agreement via cla-assistant.io. The CLA bot automatically checks status on each PR and blocks merge until signed. You only need to sign once. 4

If the CLA check gets stuck after signing (a known cla-assistant bug), comment /check-cla on the PR to retrigger it. This triggers a GitHub Actions workflow that calls the cla-assistant.io API directly. 5

Step 3 — PR Standards#

The PR template enforces: 6

• Title: must follow Conventional Commits — e.g., feat(web): add trace filters or fix: handle empty dataset names. 7
• Issue link: reference the issue number (Fixes #<number>). 8
• Type of change: mark whether the PR is a bug fix, new feature, breaking change, chore, or refactor. 9
• Mandatory self-review: a decent-sized PR without self-review may be rejected. 10
• Checklist (negative framing — mark items if you haven't done them): code style (pnpm run format), comments in hard-to-understand areas, documentation check, lint warnings (npm run lint), test coverage. 11
• Visual changes: include a Loom video to speed up reviews. 12

PRs are squash-merged into main to keep a clean conventional-commit history. 13

Step 4 — Testing Requirements#

All tests run against a live Langfuse instance and write/delete real data. They all run in CI and must pass before merge. 14

Test isolation setup#

Create .env.test from .env.test.example to use a separate langfuse_test PostgreSQL database and Redis database 1 instead of the default dev database. 15

Running tests#

Run a specific test: pnpm test --testPathPatterns="<file>" --testNamePattern="<name>" 16

CI pipeline (GitHub Actions)#

Configured in .github/workflows/pipeline.yml. On every PR and main push, CI runs: 17

• Linting
• Jest E2E API tests
• Playwright E2E UI tests

Docker images are published to GitHub Packages only after all CI checks pass on main. 18

OpenAPI / SDK Changes#

If the PR modifies API endpoints, update the Fern spec files in fern/apis/... and regenerate the OpenAPI output: 19

npx fern-api generate --api server # server API
npx fern-api generate --api client # client API
npx fern-api generate --api organizations

A signed Fern account is required to run these commands.

License#

Langfuse is MIT licensed, except for the ee/ folder. Contributors must agree to the CLA at cla-assistant.io/langfuse/langfuse. 20

Key References#