Registering a Scaffolder template

​

Creating a Scaffolder template

1. A Git integration with write access. The following integrations are available:
   1. Azure DevOps - Configure the Azure DevOps token with Code read, write & manage access.
   2. Bitbucket
      1. Cloud - Configure the Bitbucket token with Repositories - admin and delete scopes.
      2. Data Center - Bitbucket Data Center uses OAuth for authentication rather than workspace tokens. The configured OAuth credentials must have permissions to:
         1. Read the source repository being cloned
         2. Create a new repository
         These permissions can be granted in several ways, including repository-level permissions or global read/write permissions. Choose the approach that best fits your organization’s access policies.
   3. GitHub - Cortex’s GitHub app is pre-configured with permissions for the Scaffolder.
   4. GitLab - Configure the GitLab access token with write permissions.
2. Configure your username’s identity mappings for your Git provider.

​

Step 1: Creating a Cookiecutter template

​

Using a Cookiecutter 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.
3. In the file, add a version key and enter the version number. This lets Cortex record the template version used for each project in the Catalog, so you can track which projects are running outdated templates.
   
   {
   "project_name": "My Project",
   "database": ["postgres", "mysql"],
   "version": "0.1.2"
   }
   
4. Follow the Cookiecutter instructions to generate the project.

​

Creating a new Cookiecutter template

​

Step 2: Adding the template to Cortex

1. From the main sidebar, select Workflows.
2. In the upper-right corner of the Workflows page, click Register Scaffolder template.
3. Configure the template:
   • 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. Below 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. When enabled, Cortex uses the selected configuration for all Git operations (e.g., fetching the template details, populating the form options, and creating the new repo or Pull Request). The form options will be filtered to only those organizations or repositories that the selected configuration has access to.
     • With this setting disabled, you can use a single Scaffolder template with multiple organizations/configurations. While the selected configuration must still have to access the template’s repository, the remaining Git operations will be run dynamically based on the user’s form selections. The Scaffolder form options will be populated using data from all configurations. Then, Cortex will automatically use a configuration with access to the selected organization (if scaffolding a new repository) or repository (if scaffolding a new PR) for all remaining Git operations.
   • Git URL - Enter the git URL where your template lives, e.g. https://github.com/cortexapps/cookiecutter-employee
   • Git ref (optional) - Enter a git ref (branch name, tag, or commit SHA) to pin the template to a specific version of the repository. For example, entering v1.0.0 will always pull the template as it existed at that tag, regardless of subsequent changes to the default branch. If left blank, the template will pull from the default branch.
   • Subdirectory for Cookiecutter template (optional) - 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:
     • 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.
     • Both. Enable both “New service” and “New pull request” configurations.
     • Neither. Disable both “New service” and “New pull request” configurations.
   • Visibility - When creating a new repository choose the default visibility of the repository. If you do not specify, the template defaults to setting a new repository as private.
     • The available options depend on the Git provider. The Public setting only works if the org containing the repository allows it. The Internal setting only works for GitHub Enterprise accounts.
     • When running a Workflow that contains a Scaffolder block, you can configure an override to change the repo visibility.
   • 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.

​

Step 3: Create a Workflow with a Scaffolder step

​

View Scaffolder templates

​

Troubleshooting and FAQ