Fork me on GitHub

Pulumi GitHub Actions

Pulumi’s GitHub Actions help you deploy apps and infrastructure to your cloud of choice, using nothing but code in your favorite language and GitHub. This includes previewing, validating, and collaborating on proposed deployments in the context of Pull Requests, and triggering deployments or promotions between different environments by merging or directly committing changes.

Let’s see how to get started – it’s easy!

Note: Remember that GitHub Actions is in private beta right now. Please register for access here. Until you’ve been added, the Actions tab won’t show in your repos, and the .pulumi/main.workflow file will do nothing. Also note that these features will only work on private repos in the specific account that has been granted access.

Pre-Requisites

Before proceeding, you’ll need to Sign Up for Pulumi (if you haven’t already).

For your workflow to do anything interesting, you’ll want to create a new project. There are three ways to do this:

  1. Clone an Existing Example
  2. Use the New Project Wizard
  3. Download the CLI and run pulumi new to select a template

Creating a Workflow

Although the full power of the Pulumi CLI is available to use with GitHub Actions, we recommend starting with our standard workflow. This workflow consists of two actions

  1. Pulumi Deploy (Current Stack) deploys a commit to the current branch by running pulumi up
  2. Pulumi Preview (Merged Stack) shows a preview of what would happen if a PR was merged, by running pulumi preview

From here, there are two ways to configure actions in your repo: doing it manually by committing workflow files and configuring secrets, or using the visual editor. We’ll start with the file-based approach – but, if you prefer the interactive workflow editor, please scroll down.

Committing the Workflow File

Let’s get started by adding the workflow file.

To set up the workflow to run anytime you commit or modify a PR, add the following to .github/main.workflow:

workflow "Update" {
    on = "push"
    resolves = [ "Pulumi Deploy (Current Stack)" ]
}

action "Pulumi Deploy (Current Stack)" {
    uses = "docker://pulumi/actions@v0.16.0"
    args = [ "up" ]
    env = {
        "PULUMI_CI" = "up"
    }
    secrets = [
        "PULUMI_ACCESS_TOKEN"
    ]
}

workflow "Preview" {
    on = "pull_request"
    resolves = "Pulumi Preview (Merged Stack)"
}

action "Pulumi Preview (Merged Stack)" {
    uses = "docker://pulumi/actions@v0.16.0"
    args = [ "preview" ]
    env = {
        "PULUMI_CI" = "pr"
    }
    secrets = [
        "PULUMI_ACCESS_TOKEN"
    ]
}

This file is also available here.

Now you’ve got a workflow defined, but before you’re ready to use it, you’ll need to configure your secrets.

Configuring Your Secrets

After committing the workflow file into your repo as .github/main.workflow, head on over to your repo’s Settings tab, where you will find the new Secrets area:

Secrets

First, create a Pulumi Access Token, and enter it as PULUMI_ACCESS_TOKEN. This enables your GitHub Action to communicate with the Pulumi service.

Next, you’ll need to configure your cloud credentials. This is dependent on your cloud of choice; for example

  • AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY for AWS
  • ARM_CLIENT_ID, ARM_CLIENT_SECRET, and ARM_TENANT_ID for Azure
  • GOOGLE_CREDENTIALS for GCP
  • KUBECONFIG for Kubernetes

Enter these as secrets, just like you did PULUMI_ACCESS_TOKEN, so that your GitHub Action can deploy to your cloud.

Branch Mappings

Pulumi has a concept of stacks, which are isolated environments for your application (e.g., production, staging, or even distinct services). By default, the GitHub Action will assume a project has a single stack, and will associate the master branch with it. For sophisticated scenarios, this can be overridden in the .pulumi/ci.json file.

This is simply a JSON map. For example:

{
    "master": "production",
    "staging": "staging"
}

Often, we’ll map master to a production stack, and staging to a distinct staging stack, for example, and then use Pull Requests to promote code between the two. This mappings file is intentionally flexible.

Note that you’ll need to create these stacks in the usual way using Pulumi’s service console or CLI. After setting this up, everything will be on autopilot.

Try It Out!

To try things out, simply create a Pull Request or commit, and you will see these new actions showing up in the usual GitHub Checks dialog, with a green checkmark if everything went as planned:

Action Checks

Click the Logs pane to see the full output of the Pulumi CLI, along with a hyperlink to your deployment on Pulumi’s Cloud Console with more details:

Action Logs

For even better Pull Request integration, make sure to also install our GitHub App!

Action Pull Requests

Using the Visual Editor

All of the above can be done using the visual editor if you prefer. We have listed the manual instructions because not everybody will see the new UI while GitHub Actions is in preview. But after your initial setup, this UI will become available, and you may find it more convenient to edit things visually.

  1. Go to your repo on GitHub, and click on the new Actions tab:

    Editor Actions Tab

  2. Click the Create a new workflow button:

    Editor Create Workflow

  3. Click the <> Edit new file tab:

    Editor New File

  4. Replace the default workflow with the suggested Pulumi workflow described above ( see here):

    Editor Workflow Edit

If you select the Visual editor tab, you’ll see the resulting workflow actions, and all secrets may be edited:

Editor Visual Edit

To edit your secrets, scroll down and select the first Pulumi action, and click Edit:

Editor Edit

This will open the action editor on the right-hand side, in which you’ll enter your various credentials (for Pulumi and your cloud). After configuring these, you should see the green secrets with lock icons show up for your actions:

Editor Secrets

Using a Different Root Directory

By default, the Pulumi GitHub Action assumes your Pulumi project is in your repo’s root directory. If you are using a different root directory for your project, simply set the PULUMI_ROOT variable in your workflow. For example

action "Pulumi Deploy (Current Stack)" {
    ...
    env = {
        "PULUMI_ROOT" = "infra"
    }
}

This tells Pulumi that the project can be founder underneath the repo’s infra directory.

Demos and Examples

To see some examples of this in action, see the following links: