Internally hosted integrations

Integrating internally hosted services into Cortex

You can use Cortex Axon Relay to source data from an internally-hosted system and reflect that data in Cortex. Cortex Axon is a framework that can be used to build jobs that run in your environment and securely send data to Cortex.

Use Axon Relay to allow Cortex to access internally-hosted integrations including Bitbucket, GitHub, GitLab, Jira, Prometheus, and SonarQube.

You can also use Axon Relay to call internal service endpoints via a Workflow in Cortex.

This feature is available in private beta. Please reach out to your Cortex Customer Success Manager for access.

How to use Cortex Axon

Axon is composed of an agent which runs in a Docker container (cortex-axon-agent) and integrates with Kubernetes, creating a secure tunnel between the broker and Cortex.

Prerequisites

Before getting started:

• Create an API key in Cortex.

• Create authentication credentials for the integration you're configuring.

Step 1: Set up the Cortex Axon agent

Step 1.1: Configure the Relay in Cortex

1. In Cortex, navigate to Settings, then click the integration you are configuring.

   

2. On the integration's settings page, click Add configuration.

3. For the configuration type, select Relay.

4. Enter an alias for the configuration and configure any other necessary fields. At the bottom, click Save.

Step 1.2: Create a .env file and a docker-compose.yml file

• Locally on your machine, create a file called .env. Inside the file, add contents for the integration you are configuring:

Docker Compose

See the variables for your integration in the README.

For example, for GitLab you would add:

CORTEX_API_TOKEN=your_cortex_token
GITLAB_TOKEN=your_gitlab_token

Kubernetes

More information will be coming soon on Kubernetes deployments.

• Locally on your machine, create a file called docker-compose.yml. Inside the file, add contents for the integration you are configuring:

GitHub

services:
  axon:
    image: ghcr.io/cortexapps/cortex-axon-agent:latest
    env_file: .env
    env:
      - GITHUB_API=api.github.com
      - GITHUB_GRAPHQL=api.github.com/graphql
    command: [
      "relay",
      "-i", "github",
      "-a", "github-relay", # this is the alias you set up in the Cortex UI

      # if you are using a Github App token, add the following line
      # "-s", "app",
    ]

Other

For integrations other than GitHub, use the following format.

Make sure to replace INTEGRATION under env:, and any mentions of integrationName, with the name of the integration you are configuring.

services:
  axon:
    image: ghcr.io/cortexapps/cortex-axon-agent:latest
    env_file: .env
    env:
      - INTEGRATION_API=api.integrationName.com
    command: [
      "relay",
      "-i", "integrationName",
      "-a", "integrationName-relay", # this is the alias you set up in the Cortex UI
    ]

Step 2: Run the agent

Run the agent in a production environment

In a production environment, you will use a Helm chart, provided by Cortex.

Run the agent in a sandbox environment

1. In your CLI, run the command docker compose up.

   • You should see the agent start and connect to Cortex.

2. Verify that your agent is working:

   1. In Cortex, go to Settings then click the integration to view its settings page.

   2. Next to the Relay configuration you set up in the previous steps, click the play icon to test the integration.

      • If you watch the logging output in your CLI, you should see the agent receive the request and forward it to your internal service/

      • The page in Cortex should display a success message.