Compass Scaffolder CLI

CLI tool to create sync and run templates for Atlassian Compass.

Getting Started

Set up the template repository

Make sure you are on node version 20 or higher.

Initialize a template repository by running

npx @atlassian/compass-scaffolder@latest init my-templates-repo

If this fails, try installing the package globally and running

npm install -g @atlassian/compass-scaffolder
compass-scaffolder init my-templates-repo

This will create a new repository with name my-templates-repo in the current directory with the following structure:

├── compass-scaffolder.config.ts
├── compass-scaffolder.schema.json
├── .github
     └── workflows
          └── compass-push-templates.yml # workflow that runs to sync templates from this repo to Compass
          └── run.yml # workflow that runs when a template is invoked from Compass
├── templates
     └── example.yml
├── actions
     └── example.ts
├── tsconfig.json
├── package.json

Go to the my-templates-repo and run npm install (or yarn install if you use yarn) to install the dependencies.

Initiate the repo as a git repository with git init and commit the changes. Your default branch must be called main.

Update the compass-scaffolder.config.ts file and update compass credentials

const config = {
  ...otherConfig,
  compassSiteUrl: "https://your-company.atlassian.net",
  compassUsername: "your-email",
};

Generate an Atlassian token from your profile settings in Atlassian and keep it handy.

Create a new empty repository in your Github org.

Go to your repository settings -> Secrets and Variables -> Actions and create a new repository secret with the name COMPASS_API_TOKEN and the value of the Atlassian token you generated.

Push the my-templates-repo to the new repository you created.

git remote add origin "link-to-your-repo"
git push -u origin main # it must be called main

Go check the Actions tab in your repository and you should see a new workflow running. This workflow will try to sync the templates under the templates directory to Compass.

Upon finishing the workflow, Visit to https://your-company.atlassian.net/compass/templates and you should see the templates just synced from the template repository!

Set up the Compass Github app

Install the Github app and connect your Github organization in your Compass instance if you haven't already. At the bottom of the Github app settings page look for the section Template Settings with two fields:

• Template repository url: This should be the url of the repository you created in the previous step.
• Github token: This should be a classic Github API token with full repo scope of the template repository w e created in the previous step. This token is needed to invoke a template via dispatch_workflow Github API calls.

Using a template

Visit the templates page in Compass at https://your-company.atlassian.net/compass/templates and you should see the templates you synced in the previous step.

• Click Use on the template you want to use.
• Fill up the component details in the first step. This is the component that will be created as a result of the template run.
• Go to the 2nd step and fill up the template variables.
• This form is rendered based on the parameters defined in the template's yml file
• Click next, review the changes and click submit.

This will trigger the Github workflow in the template repository. Compass will show you a success page once workflow is completed.

Defining parameters

The templates follow the schema defined in the compass-scaffolder.schema.json file.

The parameters section

The parameters for a template are defined in the parameters section of the template yml file. Compass currently support the following types of parameters:

• Text:

parameters:
  required:
    - myParam
  properties:
    myParam:
      title: Name
      type: text
      default: "my default value"
      description: Some description

• Number

parameters:
  properties:
    myParam:
      title: Age
      type: number
      description: Some description

• Checkbox

parameters:
  properties:
    myParam:
      title: Enable something
      type: boolean
      description: Some description

• Single Select

parameters:
  properties:
    myParam:
      title: Select tech stack
      type: string
      description: Some description
      oneOf:
        - const: spring
          title: Spring Boot
        - const: express
          title: Express JS

• Multi Select

parameters:
  properties:
    myParam:
      title: Labels
      type: array
      description: Some description
      items:
        type: string
        oneOf:
          - const: label1
            title: Label 1
          - const: label2
            title: Label 2

You can provide any other supported json schema properties for each of the parameters as well for validations. For example:

parameters:
  properties:
    myParam:
      title: Name
      type: number
      description: Some description
      minimum: 1
      maximum: 10

The steps section

The steps section of the template yml file defines the steps that will be executed when the template is run. A step comes from an action that implements the backstage action interface. You can use any of the available backstage actions following their docs.

Compass scaffolder also ships a generic http action builder you can use to build your own http actions to make APi calls to external systems as part of your template run. Check the actions section for more details.

You can access all the available actions in the runtime with

npm compass-scaffolder action list

And access the description, schema and examples of an action with

npm compass-scaffolder action info '<action-id>'

Local development

Compass scaffolder CLI provided a run command that's essentially invoked in the Github workflow when you run a template from Compass.

You can test your templates locally before pushing them to the repository by running

npm run <template-slug> '{"some": "parameter"}'
# or yarn run <template-slug> '{"some": "parameter"}'

The template slug is the name of the yml file in the templates directory without the .yml extension. The second argument is a JSON string that represents the parameters that will be passed to the template.

Actions

Check the actions/example.ts file on how to write your own custom actions.

Compass scaffolder CLI provides a generic http action builder you can use to build your own http actions to make APi calls to external systems as part of your template run.

Here is an example of how to create a custom http action to create a Jira issue:

import { createHttpAction } from "@atlassian/compass-scaffolder";

const jiraIssueCreateAction = createHttpAction({
  debug: true,
  id: "jira:issue:create",
  description: "Creates a Jira issue",
  getDefaults: async (config: any) => {
    return {
      headers: {
        "Content-Type": "application/json",
        Authorization:
          "Basic " +
          btoa(
            `${config.config.get("jira.email")}:${config.config.get(
              "jira.apiToken"
            )}`
          ),
      },
    };
  },
});

Add the action under actions array in compass-scalfolder.config.ts file and add the config for Jira

const config = {
  ...otherConfig,
  config: {
    jira: {
      email: "your-email",
      apiToken: process.env.JIRA_API_TOKEN, // you can update the .github/workflows/run.yml file to inject the variable from a Github secret
    },
  },
  actions: [...otherActions, jiraIssueCreateAction],
};

Now you should be able to use it in your template yml file

steps:
  - id: jira_issue
    action: jira:issue:create
    parameters:
      url: https://your-company.atlassian.net/rest/api/3/issue
      method: POST
      body:
        fields:
          project:
            key: ${{ parameters.jiraProject }}
          issuetype:
            id: ${{ parameters.jiraProject }}
          summary: "Security Review Checklist for ${{ parameters.__componentInfo.name }}"
  - id: echo
    action: compass:example:echo
    input:
      data: ${{ steps.jira_issue.output.key }}