10. Using the Scaffolder
Cortex's Scaffolder extends the power of the leading templating library Cookiecutter, which allows engineers to automate the creation of code, while adhering to standards with ease.
With the Scaffolder, we've extended these abilities to enable developers to not only create a new service, but add functionality to existing services, too.
Before you can use the Scaffolder, you'll need to register templates from a repo into Cortex.
This ability is only available to admins.
You can access the Scaffolder from the Tools tab in the main nav.
From there, you'll decide whether to Create a new service or Add to an existing service.
Create a new service
Create a new service is best when you're working on an entirely new project that should ultimately be added into the catalog. Everything from front-end libraries to data pipelines can be created through the Scaffolder.
Once you select Create a new service, click on one of the available templates to move on to the next stage.
First, you’ll be asked to provide some essential information for your service — these fields will vary depending on the template you select. In this case, since we're adding an API client service, we need to add an integration name and slug, and the associated license.
Once you’ve entered in the template fields, you can decide whether to Create a new repo or Open a pull request. If you choose to create a new repo, you'll be prompted to select a Repo Org from a dropdown, name the new repo, and identify the default branch to be used for the repo.
If you want to add custom GitHub secrets to the repository, you can do so under Advanced Configuration.
If you choose to Open a pull request, you'll select the Repo Name from a dropdown list, define the branch to create where the generated code will be pushed, and identify the subdirectory where the generated code will live.
The final step is to Configure service. At this stage, you'll be prompted to enter details about your service, just like when importing entities.
Your new service will eventually be added into All entities and applicable catalogs. To maximize the functionality of your service, it makes sense to add as much of this information upfront as possible.
In addition to service details, you can also add the service to groups, designate owners, and define dependencies during this step.
Once you've added all of this information, select Create Service to confirm all of the details you entered. When you click Create Service, Cortex will create or connect with the repository in Git, run Cookiecutter, generate the code, and push the code to the appropriate Git repo.
The new service will also appear in All entities and applicable catalogs, complete with its own YAML file, so you’ll continue to have full control over your projects.
Add to an existing service
With the Scaffolder, you can Add to an existing service with a template by opening a pull request against an existing repository. If your organization uses a monorepo, or if you have an existing service you need to update, this is the option for you.
Select one of the available templates to use to Add to an existing service to move on to the next stage. Just like with Create a new service, the first stage is defining the template inputs — again, these will vary depending on the template you've selected.
Next, select the appropriate repo from the dropdown list and name the Branch to create.
Once you’ve entered in the repository information, Cortex will create this branch in Git and open a pull request against the repo.
When working with the Scaffolder, Cortex will surface any errors to the UI (even if the errors are within the Cookiecutter file), so you’ll have a clear sense of how to correct the code.
Going further
There are a suite of features within the Scaffolder that extend the powerful functionality of Cookiecutter. To learn how to hide fields, add descriptions to input fields, and much more, check out this article on advanced usage.
Disabled settings
Cortex has disabled certain Scaffolder features - primarily hooks - to close a serious security vector. The Workflows tool offers a great way to fill the gap.