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 Service 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 Service 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 about the service
  • You always own the data
When should I switch to GitOps?

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 Service Descriptor files, which allows you to make the switch in less than 5 minutes.

Disable UI editing to enable GitOps

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 no default branch is defined.
  3. The file must be in the root of the repository 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 Service 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 Service 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.

info

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!

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"