Skip to content

Basics

Official Integrations

We support multiple integrations to automatically parse your cortex.yaml files.

⭐️ Github

The GitHub integration is the easiest way to get started. We offer an official Github app that will automatically process a cortex.yaml file at the root of your repository on every push to the default branch (e.g. master). This functionality is automatically enabled once the app is installed.

The build will fail if the YAML file is not valid.

We currently recommend the Github app as the best way to integrate with Cortex.

Disable UI editing to enable GitOps

By default, Cortex allows you to update the YAML and add fields directly through the dashboard. To enable the GitOps style approach, you'll have to disable UI editing in Settings → Preferences.

This is to ensure consistency - any changes made through the UI will be overwritten by changes to cortex.yaml in the git repo."

Gitlab

We also support Gitlab. Due to the lack of support for applications, Gitlab support requires setting up a webhook for each of your projects, so that Cortex is notified when changes are made to the cortex.yaml file.

As a prerequisite, first follow the Gitlab integration setup instructions. Once you've connected Cortex with Gitlab:

  1. Create a secret token for your Gitlab webhook from the Cortex dashboard (Settings → Gitlab)
  2. In Gitlab, navigate to Your Project → Settings → Integrations
  3. Create a new Webhook and use https://api.getcortexapp.com/api/v1/gitlab/webhook as the URL
  4. Enable Push Events for the webhook
  5. Add the secret token you created in step 1 to the webhook configuration. This token allows us to verify your webhook events.

Once you've followed these steps (and your access token is set up according to the Gitlab configuration), Cortex will begin processing any changes to the cortex.yaml file when it's updated in the master or default branch.

Bitbucket

We have a Bitbucket app that will automatically parse the cortex.yaml file at the root of your repository on every push to the default branch (e.g. master). This functionality is automatically enabled once the app is installed.

Get started at Settings → Bitbucket.

You'll need to enable development mode to use the Cortex app. You can find this setting at https://bitbucket.org/{your_workspace}/workspace/settings/addon-management/.

Once you've installed the app, Cortex will automatically parse any changes to cortex.yaml when it's updated in the default branch.

Disable UI editing to enable GitOps

By default, Cortex allows you to update the YAML and add fields directly through the dashboard. To enable the GitOps style approach, you'll have to disable UI editing in Settings → Preferences.

This is to ensure consistency - any changes made through the UI will be overwritten by changes to cortex.yaml in the git repo."

Custom integrations

Upload API

If you have a custom integration needs, you can use our API to upload the YAML file.

  1. Create an API key on the Cortex dashboard (Settings → API Keys)
  2. Upload it as a file to https://api.getcortexapp.com/api/v1/open-api with the API token set as a header: Authorization: Bearer <token>.

For example:

curl
  -v
  --data-binary @cortex.yaml
  -X POST
  -H "Content-Type: application/openapi"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/open-api"

We suggest uploading this file as part of your CI/CD process so that the documentation never goes stale.

Dry Run

This API also accepts two optional parameters:

  • dryRun(boolean): whether or not to persist the changes being uploaded. This API can be used to lint your YAML file, or to check for breaking API changes as part of a CI process. Defaults to false.
  • githubPullRequest(int, ID of the pull request): in conjunction with the dryRun flag, Cortex can optionally comment on a pull request with breaking changes, if any are detected. This requires Github to be connected to cortex. See Github integration details.

Example:

curl
  -v
  --data-binary @cortex.yaml
  -X POST
  -H "Content-Type: application/openapi"
  -H "Authorization: Bearer <token>"
  "https://api.getcortexapp.com/api/v1/open-api?dryRun=true&githubPullRequest=17"