Creating Pulumi templates

Pulumi templates are pre-configured project scaffolds that you can use with pulumi new to quickly bootstrap new projects. You can create custom templates to share infrastructure patterns, enforce organizational standards, or simplify project setup for your team.

What is a template?

A template is a directory containing:

• A Pulumi.yaml file with a template section that defines configurable parameters
• Source code files for your Pulumi program
• Any additional configuration files needed for the project

When someone runs pulumi new with your template, Pulumi copies these files to their local directory and prompts them to fill in the configuration values you’ve defined.

Template structure

A basic template has the following structure:

my-template/
├── Pulumi.yaml
├── index.ts          # or main.py, main.go, etc.
├── package.json      # language-specific dependency files
└── README.md         # optional but recommended

The Pulumi.yaml file

The Pulumi.yaml file must include a template section to be recognized as a valid template. Here’s an example:

name: ${PROJECT}
runtime: nodejs
description: ${DESCRIPTION}
template:
  displayName: My Custom Template
  description: A template for deploying widgets to AWS
  config:
    aws:region:
      description: The AWS region to deploy into
      default: us-west-2
    instanceType:
      description: The EC2 instance type
      default: t3.micro
    apiKey:
      description: Your API key for the widget service
      secret: true
  metadata:
    cloud: aws
    category: compute

The template section supports these fields:

Each config value can specify:

Variable substitution

Templates support these placeholder variables in any file:

Use ${PROJECT} in your Pulumi.yaml name field and in code comments or documentation to personalize the generated project.

Using templates from Git repositories

You can use templates from any Git repository by providing the URL to pulumi new:

Public repositories

# GitHub
pulumi new https://github.com/myorg/my-template

# GitLab
pulumi new https://gitlab.com/myorg/my-template

# Bitbucket
pulumi new https://bitbucket.org/myorg/my-template

# Any Git host
pulumi new https://git.example.com/myorg/my-template.git

Subdirectories

If your template is in a subdirectory of the repository:

pulumi new https://github.com/myorg/templates/tree/main/aws-typescript

Branches and tags

To use a specific branch or tag:

# Branch
pulumi new https://github.com/myorg/my-template/tree/develop

# Tag
pulumi new https://github.com/myorg/my-template/tree/v1.0.0

GitLab subprojects

For GitLab repositories with subprojects, append .git to disambiguate:

pulumi new https://gitlab.com/mygroup/mysubgroup/my-template.git

Private repository authentication

To use templates from private repositories, you have several authentication options:

SSH authentication

Ensure your SSH agent has the correct identity loaded:

# Add your SSH key to the agent
ssh-add ~/.ssh/id_rsa

# Use SSH URL format
pulumi new git@github.com:myorg/private-template.git

For SSH URLs with a non-standard user:

pulumi new myuser@git.example.com:myorg/my-template.git

If your key requires a passphrase:

PULUMI_GITSSH_PASSPHRASE=yourpassphrase pulumi new ssh://git@github.com/myorg/private-template.git

HTTPS with credentials

You can embed credentials in the URL (use with caution):

pulumi new https://username:token@github.com/myorg/private-template.git

For GitHub, use a personal access token instead of your password.

Git credential helpers

If you have Git credential helpers configured (such as the GitHub CLI or Git Credential Manager), Pulumi will use them automatically when you use HTTPS URLs:

# If gh auth login has been run, this will work automatically
pulumi new https://github.com/myorg/private-template.git

Testing templates locally

You can test a template by providing a local file path:

pulumi new ~/templates/my-aws-template

cd /tmp
mkdir test-project
cd test-project
pulumi new ~/templates/my-aws-template

Sharing templates

You can share templates in several ways:

Git repositories

The simplest approach is hosting your template in a Git repository. Users can then run:

pulumi new https://github.com/myorg/my-template

Organization templates

For Pulumi Enterprise and Business Critical customers, you can publish templates to your organization’s Private Registry. This provides:

• Version management with semantic versioning
• Integration with the Pulumi Cloud console
• Access control through your organization settings

See Organization Templates for details.

Multiple templates in one repository

You can organize multiple templates in a single repository:

templates/
├── aws-typescript/
│   ├── Pulumi.yaml
│   └── index.ts
├── aws-python/
│   ├── Pulumi.yaml
│   └── __main__.py
└── azure-go/
    ├── Pulumi.yaml
    └── main.go

Users can then reference specific templates:

pulumi new https://github.com/myorg/templates/tree/main/aws-typescript

Best practices

1. Include a README.md - Document what resources the template creates and any prerequisites.

2. Use sensible defaults - Provide default values for configuration where possible, but make them easy to override.

3. Keep secrets secret - Mark sensitive configuration values with secret: true.

4. Test your template - Create a project from your template and verify it works as expected.

5. Version your templates - Use Git tags or branches to maintain stable versions.

6. Document configuration - Write clear descriptions for each config value so users understand what they’re providing.

See also

• Project file reference - Full reference for Pulumi.yaml including all template options
• pulumi new command - CLI reference with all available flags
• Organization templates - Enterprise template management features