Use a template

Speed up your software creation workflow by using templates that integrate best practices and adhere to your organization’s standards.

When you create a component from a template, you fork the template’s repository to use as boilerplate code. You also invoke any webhook that was added to the template, to automatically notify another part of your toolchain that you created a new component.

Learn more about templates

Before you begin

Install a supported source code management app

1. In the main navigation, select Apps.

2. Find the Bitbucket or GitHub app and select Install.

Once the app is installed, you need to configure the app so it can connect to your repositories.

Configure the Bitbucket app with a workspace

1. In the main navigation, select Apps.

2. Find the Bitbucket app, select Configure, and allow the app to access your Atlassian account.

3. Select Connect Bitbucket, and continue to Bitbucket's permissions page.

4. The Authorize for workspace list displays the workspaces that you are an admin of. Select a workspace to connect with Compass.

5. Select Grant Access.

Once you’re connected to a Bitbucket workspace, you’ll be taken back to the Bitbucket app in Compass.

Configure the GitHub app with an organization

1. In the main navigation, select Apps.

2. Find the GitHub app, select Configure, and allow the app to access your Atlassian account.

3. Select Connect GitHub, and continue to GitHub’s permissions page.

4. In GitHub, select the organization account you want to connect to.

Once you’re connected to a GitHub organization, you’ll be taken back to the GitHub app in Compass.

Check that your team has templates to use

You can’t use a template if none exist! Learn how to create a template

Use a template

1. Find the template you want to create a component from.

   • From the Templates page, hover on a template card and select Use.

   • From the Components page:

     1. Search for the template name, or use the Type filter to only show templates.

     2. Select the template you want to use.

     3. On the template’s Overview page, select Use template.

2. Fill out the basic information for the component you’ll create from the template.

   • Choose the type of component you’ll create. Learn more about component types

   • Name and describe the component, to help people generally understand it. The name you choose will also be the name of the new repository that’s forked from the template.

   • Give the component an owner team, so people know who to contact about it.

   • In the sidebar, note the repository that’ll be forked to provide the new component’s boilerplate code. You can select the repository to preview it in a new tab.

     • If the template's repository is in Bitbucket, you can choose a project to fork the repository into for your new component. If no project is chosen, a repository for the new component will be forked into the project that was first created in that workspace.

3. Select Next.

4. If the template you're using does not require any input parameters, you’ll see the Review screen where you can select Create after reviewing all information displayed.

5. If the template you're using has input parameters, you should review each one and provide a value or accept the default. These parameter values are used to further customize and configure your component. Select Next, you’ll see the Review screen where you can select Create after reviewing all information displayed.

6. You’ll be taken to your new component’s Overview page.

Your new component will:

• include the new repository that was created from the template

• have a dependency relationship with the template you created it from, which you can see on the Dependencies page

• invoke any webhook that was added to the template, so that webhook receives information about the new component including all parameter values

Next steps

1. Add more information to the component’s Overview page.

2. Link the component to any relevant work in Jira.

Troubleshooting

I can’t use the template because it’s missing a repository link

Templates need a Bitbucket or GitHub repository link, because that repository is forked when new components are created from the template. Add a repository link that is allowed to be forked from your connected Bitbucket workspace(s) or GitHub organization(s).

If there’s more than one repository link for the template, make sure the repository you want to fork from is the first in the list on the template’s Overview page.

The template’s GitHub repository couldn’t be forked

Check that:

• the GitHub app is up to date from the Apps page
• your GitHub admin has approved all necessary GitHub app permissions
• the GitHub repository is allowed to be forked
• the new GitHub repository name doesn’t already exist
• if you have multiple GitHub organizations connected, you may only fork a public repository if the repository is from your connected GitHub organization(s).

A dependency wasn’t created between a template and component

Sometimes this happens due to a network error. You’ll need to manually add the dependency relationship yourself.

Coming soon

We're working on improving templates with the following features:

• GitLab support.

• Edit templates after they’re created.

• Validate webhooks as templates are created.

• Additional parameter types, such as single select and multi-select.

• Customize webhook events to call third-party APIs when components are created from templates (for example, create a new service in Opsgenie each time a component is created from a template).