Contributing to Orbit

Thanks for contributing to GitLab Orbit, the service that turns GitLab SDLC data and source code into a queryable property graph.

Community contributions go through the community fork. GitLab team members contribute directly to this repository.

Quickstart

Install mise, then:

git clone https://gitlab.com/gitlab-org/orbit/knowledge-graph.git
cd knowledge-graph
mise install
mise build

Core tasks:

Task	Command
Build	mise build
Unit tests (no Docker)	mise test:fast
Lint	mise lint:code
Apply lint fixes	mise lint:code:fix
Validate doc changes	mise lint:docs

For the full local setup (Caproni cluster with GitLab, ClickHouse, NATS, and Siphon), see Local development.

Testing

mise test:fast runs the unit tests with no Docker. mise test:integration runs the container tests. On macOS, start Docker for them with colima start gkg --memory 12.

For all test layers, the CI jobs, and where to add a test, see Testing.

Linting

mise lint:code        # Clippy with warnings as errors
mise lint:code:fix    # Apply auto-fixable Clippy suggestions
mise lint:docs        # markdownlint + Vale + lychee link checks

Run mise lint:docs before pushing any documentation changes.

Engineering conventions

• Comments explain why. Do not narrate what the code shows.
• Reuse existing infrastructure before adding new infrastructure.
• Before changing an area, read its design document and the crate-local AGENTS.md, if present.
• Treat the ontology as the single source of truth for graph-shape facts.
• Read docs/pages/engineering/development/sox-billing-boundary.md before changing billing.

Documentation conventions

• Do not change any file under docs/ in an MR that changes code. Change it only when a CI or build check fails without it. The docs-in-code-mr-check CI job enforces this rule. When a check needs the change, add the docs-in-code-mr label and retry the job.
• Rewrite or remove stale text instead of preserving history.
• Keep README.md a front page: what GitLab Orbit is, the quickstart, and links. Put lists such as languages, entity types, and commands only in the page that owns them, and link to that page. Link to repository files by relative path, so the check_docs_markdown CI job checks each link.
• When you add, move, or remove an owning guide, update its pointers in the byte-identical AGENTS.md and CLAUDE.md files.
• Use the canonical terms in CONTEXT.md. Add a term only when a new domain concept could confuse a new contributor.
• Follow the GitLab documentation principles in .ai/principles/distilled/ when writing pages under docs/docs-gitlab-com/. A green mise lint:docs run does not mean a page follows them.

Issue conventions

• A person creates each issue and epic. An agent that runs the create call needs the author's approval of the draft first. The request to do the work is not that approval.
• Agents may draft content. The author keeps every section above the Agent context block in their own words. Put generated content in that block.

MR conventions

MR titles must follow Conventional Commits format:

type(scope): short description

Examples: fix(compiler): correct aggregation undercount, docs: add CONTRIBUTING.md.

• Non-trivial MRs (features, refactors, architectural changes) must reference an issue: Closes #N or Relates to #N.
• Trivial MRs (typos, minor dependency bumps, or formatting-only changes) do not need an issue.
• Keep each MR focused on one concern.
• Use the MR and issue templates under .gitlab/.
• Read each template's TEMPLATE CONVENTION block before you write.
• Load the /orbit-planning skill before you draft or label an issue, epic, or MR.

Keep the reviewer summary to two or three plain sentences. Describe the symptom and fix without implementation names.

Put mechanics, alternatives, and file details in the Agent context block. In comments, lead with the verdict and collapse long reasoning when it helps.

Where to start

• Open issues — the orbit::hackathon label marks good entry points.
• AGENTS.md — tooling entry point and map to the owning guides.
• CONTEXT.md — domain glossary. Use the canonical terms when writing code, docs, or MR descriptions.