Contributing

July 30, 2026 ยท View on GitHub

This is a work in progress and your help is welcome, both in the form of issues and pull requests.

When reporting a bug or requesting a feature, please be as specific as possible, and be ready to follow up. If you are not ready to follow up to make your needs more explicit, or to help with testing, don't bother requesting a new feature in the first place.

Building locally

The best way to get the dependencies is to run nix-shell (see the Nix documentation to learn more).

Without Nix, you'll need opam 2.0 installed on your system. Run opam update followed by opam switch create . -y --deps-only to install locally the required ocaml libraries.

Use the following command to build:

dune build

Committed GraphQL schemas under bot-components/github/github-schema.json and bot-components/gitlab/gitlab-schema.json are used as-is. Normal builds do not re-fetch them.

To refresh the schemas:

dune build @update-schema

Updating the GitHub schema requires bot-components/.github-token: one line with a GitHub personal access token (no special permission). It uses the get-graphql-schema npm package. Install with npm install get-graphql-schema -g if you are not in nix-shell.

After refreshing, rebuild and fix any GraphQL typing breakages, then commit the schema JSON and code changes together.

Testing locally

To test locally, we recommend using Docker for building and running the bot as a local server and ngrok to redirect webhooks coming from the web to this local server.

  1. Create an .env file defining the required environment variables.
  2. Build the bot with: docker build . -t coq-bot-local-test
  3. Run the bot with: docker run -p 8080:8080 --env-file .env coq-bot-local-test:latest
  4. Make the server accessible from the web with: ngrok http 8080
  5. Configure your repositories' webhooks with the ngrok URL.

Formatting

We use ocamlformat to auto-format OCaml and Dune files. If possible, run it with dune build @fmt --auto-promote before committing. As of today, version 0.26.2 is required.

You may also configure your editor to auto-format your files on save. If you are inside a nix-shell and using Emacs, you can simply do so by adding (load "/path/to/the/bot/dev.el") to your .emacs.