Tips and tricks for Backstage Software Templates

Jean-Louis FEREY — Wed, 09 Aug 2023 16:09:31 +0000

Intro

I'm a big fan of Backstage.

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

Software templates

There is a lot of interesting features in Backstage, but one of my favorite is the Software Templates. This feature is already well explained by Ricardo Castro on dev.to.

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.

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, simple but very good to begin,
Janus's Github which shows, among many other interesting things, a way to share some piece of templates,
Roadie's Github where you can find some tips 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:

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:

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.

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:

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

Built-in actions

There are three parts in a software template:

the parameters where you get inputs from your customer
the steps where you do some things with information collected in the first part
the output where you give some information to your customer about the tasks done by the template.

To do things in steps, you use 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:

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

Some actions have even some examples:

Conclusion

To faster you Backstage Software Templates learning curve:

learn from the community
use Backstage embedded tools
ask for help on Backstage's discord

DEV Community: Jean-Louis FEREY