LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • How to create a Cortex plugin
  • Prerequisites
  • Step 1: Register the plugin
  • Step 2: Create the plugin
  • Step 3: Clone the repository locally and install dependencies
  • Step 4: Upload and preview plugin in Cortex
  • Create a plugin proxy
  • Editing the plugin code
  • Enable dev mode
  • Edit and update the plugin
  • Share the plugin
  • Building plugins
  • Adding theme-based styling
  • Accessing contextual Cortex information from your plugin
  • Accessing Cortex APIs from your plugin
  • Accessing external APIs from your plugin
  • Using Cortex UI components

Was this helpful?

Export as PDF
  1. Plugins

Creating a plugin

Last updated 17 days ago

Was this helpful?

Plugins enable Cortex users to pull data into their Cortex instance from any source, expose custom metrics, and customize the UI to match other internal tools. A plugin is an application that is embedded in Cortex. It uses a plugin proxy to send requests from the plugin to a third party.

You can use the Scaffolder in a Workflow to quickly spin up a Cortex plugin repository. The plugin code repository includes:

  • React + TypeScript

  • Linting and formatting via and

  • Testing via

  • Compilation to a single HTML file via

  • The Cortex React plugin package () pre-installed, which provides access to context, proxy usage, CSS variables for theme-based styling, and UI components.

    • Cortex offers a with examples using react-plugin-ui.

  • The Cortex Plugin core package ().

If you created your plugin before April 2025 and your plugin is using components from plugin-core/components, we have updated these components to utilize react-plugin-ui. Please to migrate these components to the new design.

How to create a Cortex plugin

Prerequisites

Users with the Edit plugins permission can create a plugin.

Step 1: Register the plugin

  1. In Cortex, navigate to Plugins.

  2. In the upper right corner, click Register plugin.

  3. Configure the plugin:

    • Plugin name: Enter a display name for the plugin.

    • Identifier: Enter a unique identifier for the plugin.

    • Description: Enter a description of the plugin to help others understand its purpose.

    • Display icon: Select an icon that will be used when displaying this plugin across Cortex.

    • Minimum user role: Select the minimum user role required to be able to see this plugin. You can choose default or custom roles.

      • Note that you will not be able to delete a custom role if it is associated with a plugin.

    • Associated proxy: If you have configured a , select the proxy to use for proxy fetches from this plugin.

    • Context: Select the context for your proxy:

      • Global: Select this option if you want to configure the plugin to appear in your main nav or as a tab on the .

      • Specific entity types: Select this option if you want to plugin to display in the sidebar of entity pages.

      • Both options: Select this option to have the ability to display the plugin in the main nav, on the dev homepage, and on entity pages.

In the next step, you will choose how to create the plugin.

Step 2: Create the plugin

While registering your plugin, in the "Code" section of the page, you can choose whether to create a plugin repo from a template or create it from scratch.

  • Under "Create plugin," click one of the options:

    • Duplicate repo with template: Choose this option to create a plugin repo from a template.

      1. A side panel will open in Cortex, where you can configure the plugin name, license, and other details depending on which Git provider you use.

        • You can also choose whether you create a corresponding Cortex entity.

      2. When you are finished configuring the plugin, at the bottom of the side panel click Save.

    • Download template.zip: Choose this option to create a plugin from scratch.

      • A zip file will download onto your computer. You can then manually configure your repository.

In the next step, you will generate the HTML file for your plugin.

Step 3: Clone the repository locally and install dependencies

After you create a plugin from a template in Cortex, a link is displayed to see your created repository.

  1. Navigate to your newly-created plugin repository.

  2. Clone the repository locally.

  3. Install dependencies via yarn.

    • You can also use npm commands if preferred.

  4. Run yarn build to generate a single HTML file representing your plugin (output at ./dist/ui.html).

    • If you want to make any changes to the plugin, modify the code before running or re-running the build command.

  5. Navigate back to your plugin configuration page in Cortex.

Step 4: Upload and preview plugin in Cortex

  1. On the plugin configuration page, under "Upload and preview plugin," upload an HTML file you generated from running yarn build in the previous steps.

    • Dev mode: Toggle on to enable dev mode. When in dev mode, the preview for your HTML file uses code running at http://localhost:9000/ui.html. To run your plugin code from this location, use yarn dev or npm run dev from your plugin.

      • In the preview, iterate on any changes you might want to make to the plugin.

  2. Click Save plugin.

Create a plugin proxy

Editing the plugin code

Users with the Edit plugins permission can edit plugins.

Enable dev mode

Optionally, you can preview your changes before implementing them:

  1. In the row containing the plugin, click the 3 dots icon, then click Edit plugin.

  2. Next to the "Code" section, enable the toggle next to Dev mode.

    • The preview will use code running at http://localhost:9000.

  3. From your scaffolded plugin in command line, run yarn dev.

  4. View the preview on the Plugin editor page in Cortex.

Edit and update the plugin

  1. In your text editor, open the cloned repo for your plugin.

  2. After making changes and saving, run yarn build.

  3. Optionally, run yarn dev to preview your changes in Cortex.

  4. In the "Plugin code" section of the plugin editing page in Cortex, click Edit next to the file name. Select your newly-updated file.

  5. At the bottom of the page, click Save plugin.

Share the plugin

  1. In the row containing the plugin, click the 3 dots icon.

Building plugins

Adding theme-based styling

Accessing contextual Cortex information from your plugin

The easiest way to access the plugin context is via the usePluginContext() hook.

import  from "@cortexapps/plugin-core/components";
import type React from "react";

const MyComponent = React.FC => () => {
  const context = usePluginContext();

  return (
    
      Plugin context
      
    
  );
};

export default MyComponent;

If you need to access the plugin context outside of a React component, you can use the CortexApi class directly. The CortexAPI class exposed from @cortexapps/plugin-core provides a method for accessing the context your plugin is running in, getContext().

import  from "@cortexapps/plugin-core";
import types  from "@cortexapps/plugin-core";

// fetch information about the currently-signed-in Cortex user
const getCurrentCortexUser = async (): Promise => ;

// if the plugin is running inside of a catalog entity details page, fetch information about that entity
const getCurrentCortexEntity = async (): Promise => ;

Accessing Cortex APIs from your plugin

You can access Cortex APIs using @cortexapps/plugin-core’s CortexAPI.

import  from "@cortexapps/plugin-core";

// fetch deploys for the current entity if the plugin is running on a domain, resource, or service details page
const fetchDeploysForCurrentEntity = async () => {
  const context = await CortexApi.getContext();

  if (!context?.entity) 

  const  = context.entity;

  const response = await CortexApi.proxyFetch(`https://api.getcortexapp.com/api/v1/catalog/$/deploys`);
  return response.json();
};

Accessing external APIs from your plugin

It is also possible to access non-Cortex APIs from your plugin. Because plugins are run in an iframe, typical fetch requests often get blocked by the browser's enforcement of CORS. However, when using the Cortex-provided template, the browser fetch is shimmed to call CortexApi.proxyFetch, a method for using Cortex as a proxy to make the request. For this reason, you should be able to use fetch() as you typically would in a web application.

Request signing

We add the following headers to each request made by Cortex. Use these headers to verify that the request is valid and originated from Cortex:

  • x-cortex-timestamp

    • This header uses the current timestamp in millis, and is used to prevent replay attacks. Cortex will sign the requests using the format <timestamp>.<body>.

  • x-cortex-timestamp-only-signature-256

    • This header calculates the SHA256 signature using only the timestamp. Use this header in environments where the HTTP request body is unavailable due to platform limitations.

  • x-cortex-signature-256

    • This header uses the SHA256 algorithm. For security best practices, we recommend using this header rather than x-cortex-signature.

  • x-cortex-signature

    • This header uses the SHA1 algorithm and exists for backward compatibility. SHA1 is considered unsafe and this signature should be considered deprecated.

  1. Create a string with the value "$timestamp.$requestBody" if the request body is non-null OR "$timestamp" if the request body is null.

  2. Calculate an HMAC using the SHA256 algorithm. Use the Secret you provided to Cortex as the key and the string from Step 1 as the payload.

  3. Verify that the x-cortex-signature-256 matches the HMAC calculated in Step 2.

Using Cortex UI components

Cortex UI components are available for import from @cortexapps/react-plugin-ui.

If you created the plugin from a template, a link is displayed to see your created repository. Click View created repository.

To access authenticated external APIs, you can configure a plugin proxy to add request headers to requests matching a URL prefix. See for more information.

While viewing the , locate the plugin you want to share.

While viewing the , locate the plugin you want to share.

Click Share. A link is copied to your clipboard. You can share it with anyone who has access to view plugins in your Cortex workspace.

As of April 2025, all new plugins use . This package enables Cortex plugin developers to create plugins that share the look and feel of Cortex in an iframe.

Cortex offers a with examples using react-plugin-ui.

Prior to April 2025, plugins used . For existing plugins using plugin-core, ensure that you have upgraded to or above to switch your components to the new design.

The react-plugin-ui package includes CSS variables for theme-based styling. These styles will adjust to match the and will reflect your light or dark mode settings for your Cortex workspace. The styles are injected via an iframe postMessage request, which is initiated by the Cortex CortexApi.pluginInit() call.

If your plugin needs additional styling beyond what is available in react-plugin-ui, you can also use the Cortex CSS API. See documentation for these variables in the .

See the for available API calls.

If your browser fetch is not getting shimmed properly, make sure that your @cortexapps/plugin-core is up to date and you're using wrapping your app with <PluginProvider>. See the for an example.

To calculate the signature (an HMAC):

Creating a plugin proxy
plugins list in Cortex
plugins list in Cortex
the @cortexapps/react-plugin-ui package
cookiecutter template
the @cortexapps/plugin-core package
version 3.0.0-beta.4
plugin template repository
Cortex API docs
cookiecutter template
RFC2104
ESlint
Prettier
testing-library
webpack
@cortexapps/react-plugin-ui
cookiecutter template
@cortexapps/plugin-core
upgrade plugin-core to 3.0.0-beta.4 or later
dev homepage
proxy
brand color you have configured
Choose whether to use a template or start from scratch.
Upload an HTML file in the Code section.