Skip to main content

10. Using the Scaffolder

Cortex's Scaffolder tool 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 with the Scaffolder. For advanced usage information, see Scaffolder advanced usage.

scaffolder 1

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
  • GitLab
    • Configure the GitLab access token with write permissions
  • Bitbucket
    • Configure the Bitbucket token with Repositories - admin and delete scopes.
  • Azure DevOps
    • Configure the Azure DevOps token with Code read, write & manage access.

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).

Step 2: Add the template to Cortex​

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

  1. In Cortex, navigate to Tools > Scaffolder.
  2. On the left side of the page, click Add template.
  3. Configure the "Add template" form:
    • 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.
    • Git URL: Enter the GitHub 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.
    • Requires new service: When enabled, a Cortex service descriptor will be generated for the service and it will be automatically added to relevant catalogs.
      • If your template always generates a new service, we recommend enabling this setting.
    • Requires a new pull request: When enabled, the template can only be used to open Pull Requests against existing repositories. For example, you should enable this option if the template is generating infra/CI scripts or will always be used for a monorepo.
      • If your template generates a new service, but should only be used to add services to a monorepo, enable both Requires new pull request and Requires new service. In this scenario, the user will be prompted to enter a subdirectory where the generated code should live.
    • 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.
    • 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. Click Save template.

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

Running the Scaffolder​

To run the Scaffolder, you will need the Execute Scaffolder permission.

View templates​

View all templates available to your organization on the Scaffolder page in Cortex.

Create or add to services​

After you have added a template to Cortex, you can start creating new projects.

  1. On the Scaffolder page, select what you would like to scaffold:
    • Create a new service: Choose this option to create an entirely new project that should ultimately be added to the catalog.
    • Add to an existing service: Choose this option to open a pull request against an existing repository. This is a good option if your organization uses a monorepo or if you are updating an existing service.
  2. Select a template, then at the bottom of the page, click Continue.
  3. Configure the Scaffolder form.
    • If using GitHub or GitLab: When using a template to open a pull request, the form will ask for the target repository to open a PR against, and the name of the branch where the generated code will be pushed. In the case where the template creates a new service ("Requires a new service" is enabled), a third required field called subdirectory will be added. This directory is used as the target in the existing repo.
  4. At the bottom of the page, save the configuration:
    • For new services, click Create service. Cortex will create or connect with your repo, push the templated code, and add the service to the catalog (if the flag is enabled).
    • For existing services, click Run Scaffolder. Cortex will create the branch in Git and open a pull request against the repository.
note

If using the Scaffolder to create a new repo and the desired repo already exists, Cortex will throw an error and prevent the flow from continuing.