Use Pulumi Deployments with the Pulumi and GitHub CLIs

Creating a new project manually

This walk-through shows you how to create a new project using pulumi new, upload to GitHub using the gh CLI, and then configure Pulumi Deployments.

Prerequisites

Before you start, configure a version control integration for your Pulumi organization. Deployments works with any of Pulumi’s version control integrations. This walkthrough uses GitHub and the gh CLI, but the same workflow applies to any supported provider.

You will need the following tools to complete this tutorial:

• The Pulumi CLI
• The GitHub CLI

Create project and upload to a new GitHub repository

• Create a project by running pulumi new with the random-typescript template. Passing the template name and --yes accepts the default project name (the directory name), description, and stack name without prompting. This template uses the Pulumi Random provider to generate random values, so the deployment runs to completion without any cloud credentials or OIDC configuration — letting you see Deployments work end to end before wiring up a real cloud provider.

$ mkdir test_deployments && cd test_deployments
$ pulumi new random-typescript --yes
Created project 'test_deployments'
Created stack 'dev'
Installing dependencies...
Finished installing dependencies

Your new project is ready to go!

This creates a stack for you under your default Pulumi organization in Pulumi Cloud.

• Initialize the local git repository:

$ git init -b main
$ git add .
$ git commit -m "first commit"

• Create a new GitHub repository and push the local code. Replace <github_owner> with your own GitHub owner.

$ gh repo create <github_owner>/test_deployments --private --source=. --push
✓ Created repository <github_owner>/test_deployments on GitHub
✓ Pushed commits to https://github.com/<github_owner>/test_deployments.git

Configure deployment settings

Now that we have a GitHub repository, we can configure it to use Pulumi Deployments.

1. In Pulumi Cloud, select Stacks in the left navigation and open your test_deployments/dev stack.

2. From the stack page, select Settings, then Deploy in the left navigation to open the deployment settings.

3. Under Source control settings, connect the stack to your repository:

   • Select GitHub as the source control provider.
   • Select the test_deployments repository you created earlier.
   • Select the main branch.
   • Leave the Pulumi.yaml folder blank, since the project lives in the repository root.

4. The random-typescript template needs no cloud credentials, so you can leave the remaining settings at their defaults. When you later deploy a project that provisions cloud resources, this is where you’d configure things like:

   • OIDC Connect for cloud authentication
   • Environment Variables

   See Pulumi Deployment Settings for more information about the available settings.

5. Select Save deployment configuration to save your settings.

Run your first deployment

With deployment settings saved, you can run a deployment:

1. Select the Deploy button in the top right of the stack page to trigger a deployment.

2. Pulumi Cloud takes you to the deployment’s page, where you can watch the logs in real time. The deployment runs a pulumi up on managed compute, so it provisions the resources defined by your program — in this case, the random values created by the random-typescript template.

3. When the run finishes, its status changes to Succeeded. Confirm the operation completed:

   • On the stack’s Deployments page, the latest deployment shows a green Succeeded status.
   • On the stack’s Resources page, you’ll see the resources your program created.

If a deployment fails, open it to read the logs, fix the underlying issue, and select Deploy again to trigger a new deployment.

In summary, after completing this walkthrough you will have:

• A new Pulumi project and stack, created locally with pulumi new.
• Code committed and pushed to a new GitHub repository.
• Pulumi Deployments configured on your stack.
• A successful deployment that provisioned your infrastructure.

Next steps

Now that you have a stack deploying through Pulumi Deployments, here’s where to go next:

• Authenticate to your cloud without static credentials. Use Pulumi ESC to broker short-lived cloud credentials via OpenID Connect (OIDC), then reference that environment from your stack so deployments authenticate to AWS, Azure, or GCP without long-lived secrets.
• Tune your deployment settings. Review the full set of deployment settings — pre-run commands, environment variables, OIDC, and executor options.
• Preview changes on pull requests. Enable review stacks to spin up ephemeral infrastructure for each pull request.
• Detect and remediate drift. Turn on drift detection to catch changes made outside of Pulumi.
• Run operations on a schedule. Configure scheduled deployments to run pulumi up, preview, or refresh automatically.