Development notes
Local development
This document sets you up to use locally running instances of ocaml-ci-service
and ocaml-ci-web
to build an OCaml project that is in a repository owned by your GitHub user.
Setting up a GitHub App
Since ocaml-ci
is a GitHub App, create a GitHub App (settings/apps) under your own user and point it to localhost via a webhook payload delivery service like smee.io.
To do this, follow the instructions in Setting up your development environment to create a GitHub App but when it comes to setting permissions for your app, set the following as the “Repository permissions”:
Checks: Read and write
Commit statuses: Read and write
Contents: Read-only
Metadata: Read-only
Pull requests: Read-only
Also, subscribe to the following events:
Create
Pull request
Push
Running the GitHub pipeline locally
You will need the following:
- The GitHub App ID of the app you created
- The
pem
file containing the private key associated to the app - A comma separated list of GitHub accounts to allow - this could start out as just your GitHub account
- A capability file for submitting jobs to a cluster, in this case the main ocaml-ci cluster as documented in https://github.com/ocurrent/ocluster#admin
- The app webhook secret that is used to authenticate to the app
dune exec -- ocaml-ci-service \
--github-app-id <your-github-app-id> \
--github-private-key-file <path-to/private-key.pem> \
--github-account-allowlist <your-github-username> \
--submission-service <path-to-the-submission-capability-file> \
--github-webhook-secret-file <path-to-the-app-secret> \
--capnp-listen-address tcp:127.0.0.1:9001
--migration-path "$PWD/migrations"
This will generate a capability file. See the logs for Wrote capability reference to "./capnp-secrets/ocaml-ci-admin.cap"
You should see the admin site on localhost:8080
Running the GitLab pipeline locally
You will need the following:
- The GitLab API token with permissions to the repositories to build
- GitLab secret associated with webhooks
- A capability file for submitting jobs to a cluster, in this case the main ocaml-ci cluster as documented in https://github.com/ocurrent/ocluster#admin
dune exec -- ocaml-ci-gitlab \
--gitlab-token-file <your-gitlab-token> \
--gitlab-webhook-secret-file <your-gitlab-secret> \
--submission-service <path-to-the-submission-capability-file> \
--capnp-listen-address tcp:127.0.0.1:9800
--migration-path "$PWD/migrations"
This will generate a capability file. See the logs for Wrote capability reference to "./capnp-secrets/ocaml-ci-gitlab-admin.cap"
Running the web client locally
Using the capability file written out by the service, run the web client as follows:
dune exec -- ocaml-ci-web \
--backend ./capnp-secrets/ocaml-ci-admin.cap \
--gitlab-backend ./capnp-secrets/ocaml-ci-gitlab-admin.cap
You should see the client site on localhost:8090
note that both backends are optional so you can run just the github or gitlab pipelines.
Running a scheduler and a worker (OPTIONAL)
You can run a scheduler and a worker to connect it to the CI. Follow the instruction from ocurrent/ocluster.
Migrations
Migrations are managed using omigrate.
If you are using an opam switch for ocaml-ci then omigrate
should be installed and you can create a new migration by doing this from the project root:
omigrate create --dir migrations <migration-name>
This will create timestamped files in the migrations
directory that you can then populate with the sql necessary to introduce and remove the migration (in the up
and down
files respectively).
Migrations will not run unless the --migration-path
flag is present when invoking ocaml-ci-service.