Skip to main content

Basics

Although you can easily update the Catalog directly through the Cortex UI, switching to a GitOps approach provides a few benefits.

The GitOps approach involves disabling the UI editor, and making all changes to your Catalog data through a Catalog Descriptor file and syncing the changes to this file using our official Git integrations, or progamatically using our API.

Using a GitOps model with the Catalog Descriptor checked into git provides a few benefits:

  • The metadata is version controlled
  • The repository where your code lives is also the source of truth for information
  • You always own the data

We don't recommend switching to GitOps for your organization until Cortex has been broadly rolled out. We suggest allowing developers to experiment with Cortex through the UI, and having a line-in-the-sand for a GitOps cutover.

Built-in integrations

All of our official Git integrations support automatically parsing your Catalog Descriptor files, which allows you to make the switch in less than 5 minutes.

None of the GitOps integrations outlined here will work if in-app UI editing is enabled.

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 would otherwise be overwritten by changes to cortex.yaml in the git repo.

Overview

Regardless of which integration you're using, there are a few similarities.

  1. We will always look for files named cortex.yaml or cortex.yml, in that order
  2. Cortex will only check for this file in the default branch, e.g. master, unless otherwise specified. We default to master if there is no default branch defined.
  3. If using GitHub or Gitlab, the service descriptor can be located anywhere in the repository as long as the file is correctly named. We recommend putting the file in the root of the repository or in the .cortex/catalog folder; this is required when using BitBucket or Azure Devops unless otherwise specified.

GitHub

Official App

We offer an official GitHub app that comes pre-configured for GitOps with Cortex.

The GitHub app has a built in linter – If the Catalog Descriptor file is invalid, the GitHub App will comment on the PR with the outstanding issues!

Webhook

If you do not wish to use the official app, or prefer to integrate with GitHub using a Personal Access Token, you can manually add a webhook to your GitHub organization.

  1. Once you've added a PAT under Settings → GitHub, you'll see an option to set up a webhook by adding a secret.
  2. Add a secret passphrase and take note of it. This passphrase will be used by GitHub to prove that the webhook event is valid.
  3. Once you've added the secret, it'll give you a unique webhook URL.
  4. Follow the instructions from GitHub on adding an org-level webhook.
    When creating this webhook, GitHub will ask for a URL (created in step 3) and a secret (the one created in step 1). Set the content type to application/json.
  5. Start using GitOps!

GitLab

Due to the lack of native support for applications, GitLab support requires setting up a webhook so that Cortex is notified when the Catalog Descriptor is modified.

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, set up a System Hook (recommended) or a project hook.
  3. 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.
  6. Start using GitOps!

Bitbucket

Install the BitBucket app from 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/.

No other configuration needed!

Azure DevOps

Webhook

In order to use GitOps with Azure DevOps you can manually add a webhook.

  1. Navigate to Settings -> Azure DevOps and ensure your Azure DevOps integration is set up and connected.
  2. Click the Create a new webhook button and copy the unique webhook URL.
  3. Follow the instructions from Azure on adding a webhook. Make sure you set your event type to be Code pushed and use the URL generated in step 2.

API Upload

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"

Monorepos

A monorepo is defined as using one Git repository for multiple services. When using GitOps with monorepos you can use a cortex.yaml or cortex.yml file per subdirectory representing that service.

Details on the relevant configuration used are covered on the respective integration pages for GitHub, GitLab, and Azure DevOps. Bitbucket requires special considerations when using monorepos.