Skip to main content

Getting started with the Scaffolder

The Scaffolder unlocks a fully-automated workflow for spinning up new projects (including microservices, and libraries) as well as adding functionality to existing services (CI scripts, infrastructure modules, etc). Using templatization, Cortex's Scaffolder allows you to 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. Cookiecutter is the industry-standard tool to auto-generate boilerplate for your new projects.

Setting up your template

To get started with the Scaffolder, you'll need a Cookiecutter template. You can try using an existing open source template, or create your own!

Cookiecutter templates define their variables in a special cookiecutter.json file in the root of the template repository. To use an existing template with Cortex's Scaffolder product, you'll need to add a version key to your cookiecutter.json file.

Your cookiecutter.json will look something like the following:

{
"project_name": "My Project",
"database": ["postgres", "mysql"],
"version": "0.1.2"
}

This allows Cortex to track which version of the template was used to generate a given project in the Catalog.

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

Adding the template to Cortex

Once you've set up your Cookiecutter template, navigate to Settings -> Service Templates.

The Scaffolder requires Git with write access

Make sure you've set up a Git integration with write access, such as our GitHub App or a GitLab Token with write permissions.

Give your template a name, which will be seen by developers when they try to create a service using the template.

Optionally, add tags to describe the template. For example, they can help developers understand whether the template is meant to be used for creating a library/backend/frontend, which language it uses, and more.

Point Cortex to the Git repo where the template lives (with the cookiecutter.json at the root of this repo). Cortex expects only one template per repo.

Advanced options

When adding your template to Cortex, you'll notice two flags – "Requires New Service" and "Requires Opening a Pull Request". Here's how those flags work:

  • "Requires New Service" is enabled: Cortex asks the user for service details (tag, owners, etc), adds the generated project to the catalog, and generates a Service Descriptor for you.
  • "Requires Opening a Pull Request" is enabled: the template can only be used to open PRs (for ex, infra templates)

These flags enable specific use cases:

  1. If your template only generates files to be added to an existing service, such as infra modules, CI scripts, etc, then you likely want to disable "Requires New Service" and enable "Requires Opening a Pull Request".
  2. If your template always generates a new service, you'll want to enable "Requires New Service".
  3. If your template generates a new service, but should only be used to add services to monorepo, enable both flags. In this scenario, the flow will ask the user for a subdirectory in which the generated code should live.

Using your template

Once you've set up your Git provider with the right permissions, created a template, and added it to Cortex, you can start creating new projects!

In the top menu under Services → Scaffolder, you'll find all the templates that are available to your organization.

After selecting a template, fill out the form, follow the flow, and Cortex will create your repo, push the templated code, and add the service to the catalog (if the flag is enabled).

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.

Opening Pull Requests

When using a template to open a Pull Request, the flow will ask you for:

  1. The target repository to open a PR against
  2. The name of the branch where the generated code will be pushed (source branch for the PR)

In the case where the template creates a new service ("Requires New Service" is enabled), a third required field called subdirectory will be added. This directory is used as the target in the existing repo.