Building Developer Portals with Organization Templates

A large number of public project templates are provided by Pulumi in our examples and templates repos. These can be useful for teams starting from scratch; however, as your business and infrastructure grow in complexity, it is likely you will want new Pulumi projects to include some custom, internal functionality not provided by these public templates.

Pulumi allows you to define Organization Templates to help get projects off the ground faster. This enables you to provide new Pulumi projects with consistent code structure, conventions, or best practices.

Defining an Organization Template

A template can be hosted in a public or private GitHub repository, and its only requirement is that it must contain a valid Pulumi.yaml at the root or within a subdirectory of the repository. A single repository can provide multiple templates from various subdirectories.

The Pulumi.yaml file can optionally contain a template section, which typically includes a config section for specifying required config values for the project. Each config value can have a description and a default value. Config values can be marked as secret, which ensures values in templated projects will be stored with secure encryption.

name: my-aws-project
runtime: nodejs
description: My AWS project description
template:
  config:
    aws:region:
      description: The AWS region to deploy into
      default: us-west-2
    myAccessToken:
      description: My access token
      secret: true

The above snippet includes an aws:region configuration value with a default value of us-west-2, as well as a myAccessToken secret without a default value.

When a project is created from a template, the resulting project will include:

• A modified Pulumi.yaml file, which reflects the new project’s name and description.
• A new Pulumi.<stack>.yaml file, which includes populated configuration values as specified in the template section of the source Pulumi.yaml.
• A copy of all other files co-located with the source Pulumi.yaml.

Any occurrences of ${PROJECT} or ${DESCRIPTION} – in Pulumi.yaml or any other files – will be replaced with their respective values.

Using Organization Templates within your Pulumi organization

A Pulumi organization admin can configure their organization to use Organization Templates with the New Project Wizard. By doing so, your organization’s members will be able to:

• Template and configure new Pulumi projects from their browser.
• Automatically push code for new projects into new or existing GitHub repositories.
• Configure Pulumi Deployments to automatically work with new projects.

Prerequisites

GitHub App

You will need the Pulumi GitHub application installed and connected to your Pulumi organization in order to configure Deployment settings on new projects. See the GitHub app installation instructions for more details.

GitHub OAuth

You will also need to authorize Pulumi with GitHub in order to use private repositories as template sources. This authorization is needed in order to act on your behalf (and not as the Pulumi GitHub app) when fetching and creating private repositories. More specifically, this ensures that only repositories your GitHub user would normally have access can be used as template sources.

Navigating to your organization’s “Settings → Integrations” tab will show an “Organization Template Sources” section. If you have not already authorized you will see an “Authorize GitHub” button. Click the button and accept the required permissions.

Organization settings

Navigate to the “Integrations” tab to configure the Pulumi New Project Wizard to define your Organization Templates Source. Enter sources as github.com/<owner>/<repo>/<optional subdirectory>. A source can be a directory containing either a Pulumi.yaml, or other subdirectories with their own Pulumi.yaml files. For example, these are both valid sources:

• github.com/pulumi/templates (all public Pulumi templates)
• github.com/pulumi/templates/aws-typescript (a specific public template)

Private repositories work similarly as long as your GitHub user has access to the repository.

After you have configured template sources, the New Project Wizard will allow users to use those sources when creating new projects with Deployments.