LogoLogo
Login to CortexBook a DemoCortex Academycortex.ioCortex Status
  • 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
      • Semgrep
      • 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)
    • Velocity Dashboard (Beta)
  • Cortex Query Language (CQL)
    • Running and saving CQL queries
    • 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 Scaffolder template
  • Prerequisite
  • Step 1: Create a Cookiecutter template
  • Step 2: Add the template to Cortex
  • Step 3: Create a Workflow with a Scaffolder step
  • View Scaffolder templates
  • Troubleshooting and FAQ

Was this helpful?

Export as PDF
  1. Workflows

Registering a Scaffolder template

Last updated 1 hour ago

Was this helpful?

Cortex's Scaffolder allows you to build a fully-automated Workflow for spinning up a new project (including repositories and libraries) and adds functionality to existing services (CI scripts, infrastructure modules, etc). Using templates, you can automatically generate the boilerplate and plumbing for projects, ensuring they follow best practices from day 0.

Templating is powered by the open source Cookiecutter project, an industry-standard tool to auto-generate boilerplate for new projects.

This page describes how to get started using the Scaffolder as a block in a Workflow. For advanced usage information, see Scaffolder advanced usage.

Looking for a quick introduction to Scaffolder? Check out the Cortex Academy "Intro to Scaffolder" course, available to all Cortex customers and POVs.

How to create a Scaffolder template

Prerequisite

Before getting started:

  • Make sure you have configured a Git integration with write access. The following integrations are available:

    • GitHub

      • Cortex's GitHub app is pre-configured with permissions for the Scaffolder.

    • GitLab

      • Configure the GitLab access token with write permissions

    • Bitbucket

      • Configure the Bitbucket token with Repositories - admin and delete scopes.

        • Note: It is not possible to require a new Pull Request or service when using the Scaffolder with Bitbucket.

    • Azure DevOps

      • Configure the Azure DevOps token with Code read, write & manage access.

        • Note: It is not possible to require a new Pull Request or service when using the Scaffolder with Azure DevOps.

  • Make sure you have configured your username's identity mappings for your Git provider.

Step 1: Create a Cookiecutter template

To get started with the Scaffolder, you'll need a Cookiecutter template. You can either use an existing template or create a new one.

To get started quickly, you can use an existing open source template.

  1. Find an open source template and clone the repo.

  2. Open your cookiecutter.json file, located in the root of the template repository.

    • In the file, add a version key and enter the version. This allows Cortex to track which version of the template was used to generate a given project in the Catalog. For example:

    {
    "project_name": "My Project",
    "database": ["postgres", "mysql"],
    "version": "0.1.2"
    }
  3. Follow the Cookiecutter instructions to generate the project.

Security restrictions for templates

For security reasons, for templates used on Cortex Cloud, we disable Cookiecutter hooks, network access, and any syscalls. If you get an exception when using your template, ensure it's not attempting any of these restricted actions.

These features are enabled for templates when using Cortex Server (self-hosted).

  1. Create your own template. See Cookiecutter's tutorial with examples in their documentation.

    • Additional guides can be found in tech blogs, such as this one describing how to create a template.

  2. Follow Cookiecutter's instructions to generate the project.

Step 2: Add the template to Cortex

You must have the Configure Scaffolder templates permission to follow these steps.

  1. In Cortex, navigate to Workflows from the main nav.

  2. In the upper right corner of the page, click Register Scaffolder template.

  3. Configure the template details:

    • Provider: Select which Git provider you are using.

    • Name: Enter a name for the template. This will be seen by developers when they create a service using the template.

    • Description: Add a description to help others understand the template's purpose.

    • Tags: Optionally, add tags to describe the template. For example, these could help developers understand whether the template is meant to be used for a specific service type, what language it uses, and more.

  4. Under "Configuration," fill in the fields:

    • Git provider configuration: Enter the configuration, e.g., default

      • By default, the option Use this configuration for all git operations is enabled. This option will limit you to only using this configuration while configuring a Scaffolder block in a Workflow. If your configuration lacks access to the target organization in your Scaffolder, the Workflow run will fail.

      • With this setting disabled, you will be able to select which configuration you want to use while configuring a Scaffolder block. As a fallback option, Cortex will use all available configurations for this Git provider and will filter out any failed results.

    • Git URL: Enter the git URL where your template lives, e.g. https://github.com/cortexapps/cookiecutter-employee

    • Subdirectory for Cookiecutter template: If your Cookiecutter template is not stored at the root of your repository, enter the subdirectory URL here.

    • Configuration requirements: Select one of the following. Note that these options do not appear for Bitbucket or Azure DevOps, as you cannot create a service or a pull request for those providers.

      • New service. Cortex service descriptor will be generated for the service and it will be automatically added to relevant catalogs.

        • If you don't select this option, you will still have the option to create a service entity when running the Scaffolder.

      • New pull request. When enabled, the template can only be used to open pull requests against existing repositories.

        • Note: It is not possible to require a new Pull Request when using the Scaffolder with Bitbucket.

      • Both. Enable both "New service" and "New pull request" configurations.

      • Neither. Disable both "New service" and "New pull request" configurations.

    • Create cortex.yaml in git when creating a new service: When enabled, a cortex.yaml will be created in git when the Scaffolder creates a new service.

      • If you don't enable this setting, the entity descriptor will be added via the API.

    • Show README.md during Scaffolding: When enabled, the project's README.md will be displayed when inputting the variables to use while rendering the template. If there is no README.md, nothing will be shown.

  5. Click Register Scaffolder template.

If you see a "Failed to save template" error, ensure that you have provided a valid Git URL.

Step 3: Create a Workflow with a Scaffolder step

After you have added a template to Cortex, you can start using the Scaffolder in a Workflow.

Follow the instructions in the Workflows documentation for creating a Workflow and adding a Scaffolder block.

View Scaffolder templates

View all templates available to your organization under Workflows > Scaffolders.

Troubleshooting and FAQ

When running a Scaffolder and choosing from my list of Azure DevOps projects, some projects aren't appearing as expected.

This can happen if you have enabled the option Use this configuration for all git operations when configuring your template in Cortex. Disable this setting for the ability to choose from all configurations.

The template's can be found at the top of the page while editing the Scaffolder template:

Cortex ID (CID)
The CID is at the top of the Scaffolder template editing page.