Tips and tricks for Backstage Software Templates
Tags: backstage, idp, devsecops
Published: 2023-08-09 16:09:31

## Intro
I'm a big fan of [Backstage](https://backstage.io/).

If you don't know what Backstage is, have a look on this short video:

{% embed https://youtu.be/85TQEpNCaU0 %}

## Software templates

There is a lot of interesting features in Backstage, but one of my favorite is the [Software Templates](https://backstage.io/docs/features/software-templates/). This feature is already well explained by Ricardo Castro on [dev.to](https://dev.to/mccricardo/backstage-software-templates-2jf6).

I like this feature because it permit what I call "standardization by ease", in opposition to standardization by constraint when somewhere in your organization, a "code police", impose a law without telling how to implement it in your code.

With Software Templates, you can provide to your developers some state-of-the-art project (in term of coding, ci/cd, security, documentation) which will be automatically pushed in a repo of your scm system (Github, Gitlab  Bitbucket, ...). And they will follow the best practices because it helps them.

Software Templates can also be used to onboard an existing component in Backstage by creating a pull request (on Github) or a merge request (on Gitlab) which propose to the project to add in the repo the catalog-info.yaml file used by Backstage to index the project.

## Learn from the community

The best way to start with Software Templates is to learn from others.

The first place to learn is, of course, the [Backstage documentation](https://backstage.io/docs/features/software-templates/).

But, in my opinion, it's easier to see how others are building their templates. For that you should have a look on:

- [Backstage's Github](https://github.com/backstage/software-templates/tree/main/scaffolder-templates), simple but very good to begin,
- [Janus's Github](https://github.com/janus-idp/software-templates/tree/main/scaffolder-templates) which shows, among many other interesting things, a way to share some piece of templates,
- [Roadie's Github](https://github.com/RoadieHQ/software-templates/tree/main/scaffolder-templates) where you can find some [tips ](https://roadie.io/docs/scaffolder/debug-template/) to debug your templates

## Use Backstage tools

When you begin on Software Templates, as for any other languages, you make mistakes and it's a little bit boring to modify your code, to push it in your Software Templates repository, then to try it in Backstage, to see it does not work.

Fortunately, Backstage will help you with that. There is a special place in Backstage for trying and tuning your templates. You can try it on https://YourBackstageInstance/create/edit. For instance, on the [janus showcase portal](https://showcase.janus-idp.io/create/edit):

![Backstage create edit page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/p6570qesbdkuriu88rrr.jpg)

### Edit template form

When you click on Edit template form, you access to a place where you will be able to write your template, and to see immediately if it works:

![Backstage create edit template form](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pw8r3r7g27wnx7l6d834.png)

### Custom field explorer

Paraphrasing the documentation of Backstage, collecting input from the user is a very large part of the scaffolding process and Software Templates as a whole. These input are made in software templates by using custom fields, for instance the [Repository Picker](https://backstage.io/docs/features/software-templates/writing-templates#the-repository-picker).

Sometimes, it's not easy to understand all the possibilities of these objects.

Here again, you can explore them with the custom field explorer, for instance the OwnerEntityPicker:

![Backstage create edit custom field](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8v6wlesxxz56wp9ckvof.jpg)

In this example, we add group in allowedKinds to limit the choice on groups, and we can see immediately the result:

![Backstage create edit custom field result](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fm251nbtegwngegpwn5f.jpg) 

### Built-in actions

There are three parts in a software template:

- the _[parameters](https://github.com/backstage/software-templates/blob/main/scaffolder-templates/clean-architecture-app/template.yaml#L17)_ where you get inputs from your customer
- the _[steps](https://github.com/backstage/software-templates/blob/main/scaffolder-templates/clean-architecture-app/template.yaml#L93)_ where you do some things with information collected in the first part
- the _[output](https://github.com/backstage/software-templates/blob/main/scaffolder-templates/clean-architecture-app/template.yaml#L127)_ where you give some information to your customer about the tasks done by the template.

To do things in _steps_, you use [builtin actions](https://backstage.io/docs/features/software-templates/builtin-actions), and all these actions are not listed in the documentation. But there are listed directly in the application on https://YourBackstageInstance/create/actions. For instance, on the [janus showcase portal](https://showcase.janus-idp.io/create/actions):

![Backstage builtin actions page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tezs6ime0pvpo3qlkzth.jpg)

It's very useful when you want to know all capabilities of an action, for instance publish:gitlab

![Backstage builtin actions publish gitlab](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8n9tix94zmbbqwyyauwf.png)

Some actions have even some examples:

![Backstage builtin actions debug examples](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4dsgahzm9jqo5l2xxu72.jpg)

## Conclusion

To faster you Backstage Software Templates learning curve:

- learn from the community
- use Backstage embedded tools
- ask for help on [Backstage's discord](https://discord.com/channels/687207715902193673/923143744176418836)