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, a GitLab Token with write permissions, a Bitbucket Token with Repositories - admin and delete scopes, or an Azure DevOps Token with Code read, write & manage access.

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 a new service" and "Requires a new pull request". Here's how those flags work:

  • "Requires a 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 a new 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 a new service" and enable "Requires a new pull request".
  2. If your template always generates a new service, you'll want to enable "Requires a 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​

Creating services​

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 Tools → 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 (only supported for GitHub and GitLab)​

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