Awesome
Pulumi GitHub Actions
Pulumi's GitHub Actions deploy apps and infrastructure to your cloud of choice, using just 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 code.
Getting Started
name: Pulumi
on:
push:
branches:
- main
jobs:
up:
name: Preview
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pulumi/actions@v5
with:
command: preview
stack-name: org-name/stack-name
env:
PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
This will check out the existing directory and run pulumi preview
.
Configuration
The action can be configured with the following arguments:
-
command
(optional) - The command to run as part of the action. Accepted values areup
(alias: update),refresh
,destroy
,preview
andoutput
. If unspecified, the action will stop after installing Pulumi. -
stack-name
(optional) - The name of the stack that Pulumi will be operating on. Use the fully quaified org-name/stack-name when operating on a stack outside of your individual account. This field is required if acommand
was specified. -
work-dir
(optional) - The location of your Pulumi files. Defaults to./
. -
cloud-url
- (optional) - the Pulumi backend to login to. This would be the equivalent of what would be passed to thepulumi login
command. The action will login to the appropriate backend on your behalf provided it is configured with the correct access credentials for that backend. -
comment-on-pr
- (optional) Iftrue
, then the action will add the results of the Pulumi action to the PR. Ignored unless${{ github.event }}
type ispull_request
. -
comment-on-summary
- (optional) Iftrue
, then the action will add the results of the Pulumi action to the GitHub step summary. -
github-token
- (optional) A GitHub token that has access levels to allow the Action to comment on a PR. Defaults to${{ github.token }}
-
refresh
- (optional) Iftrue
, stack is refreshed before running thecommand
. -
secrets-provider
- (optional) The type of the provider that should be used to encrypt and decrypt secrets. Possible choices:default
,passphrase
,awskms
,azurekeyvault
,gcpkms
,hashivault
. e.g.gcpkms://projects//locations/us-west1/keyRings/acmecorpsec/cryptoKeys/payroll
-
color
- (optional) Colorize output. Choices are: always, never, raw, auto (default "auto").
Extra options
-
config-map
- (optional) Configuration of the stack. Format Yaml string:{<key | string>: {value: <value | string>, secret: <is_secret | boolean> },}
. -
diff
- (optional) Display operation as a rich diff showing the overall change. -
comment-on-pr-number
- (optional) If set to a number, then the action will add the results of the Pulumi action to the specified PR number. -
edit-pr-comment
- (optional) Edit previous PR comment instead of posting new one. PLEASE NOTE: that as of 3.2.0 of the Action, this now defaults totrue
. This is in an effort to reduce verbosity - if you want to have a comment per PR run, please ensure that you set this tofalse
. -
expect-no-changes
- (optional) Return an error if any changes occur during this update. -
message
- (optional) Optional message to associate with the update operation. -
parallel
- (optional) Allow P resource operations to run in parallel at once (1 for no parallelism). Defaults to unbounded. -
policyPacks
- (optional) Run one or more policy packs with the providedcommand
. Multiple values can be specified one per line (example:<value | string>,...
). -
policyPackConfigs
- (optional) Path(s) to JSON file(s) containing the config for the policy pack with the corresponding "policy-pack" argument. Multiple values can be specified one per line (example:<value | string>,...
). -
pulumi-version
- (optional) Install a specific version of the Pulumi CLI. Defaults to "^3". Specifying a version range will ensure a version within that range is installed. Use "latest" to fetch the latest published release or "dev" to download the latest development pre-release. -
pulumi-version-file
- (optional) File containing the version of the Pulumi CLI to install. Example: .pulumi.version. Only onepulumi-version
orpulumi-version-file
should be provided. -
remove
- (optional) Removes the target stack if all resources are destroyed. Used only withdestroy
command. -
replace
- (optional) Specify resources to replace. Multiple resources can be specified one per line (example:<value | string>,...
). -
target
- (optional) Specify a single resource URN to update. Other resources will not be updated. Multiple resources can be specified one per line (example:<value | string>,...
). -
target-dependents
- (optional) Allows updating of dependent targets discovered but not specified in target. -
upsert
- (optional) Allows the creation of the specified stack if it currently doesn't exist. PLEASE NOTE: This will create aPulumi.<stack-name>.yaml
file that you will need to add back to source control as part of the action if you wish to perform any further tasks with that stack. -
exclude-protected
- (optional) Skip destroying protected resources. Only valid whencommand
isdestroy
. -
suppress-outputs
- (optional) Suppress display of stack outputs (in case they contain sensitive values). -
suppress-progress
- (optional) Suppress display of periodic progress dots to limit logs length. -
plan
- (optional) Used for update plans- On
preview
: Where to save the update plan. If you choose to use this in a different run of your workflow (let's say you create an update plan via a preview on Pull Request creation and want toup
using the plan) you must upload the plan as an artifact, and retrieve it wherever you runup
- On
up
: Where to read the update plan from.
- On
-
always-include-summary
- (optional) Iftrue
, then the action will trim long pr comments from the front instead of the back. This ensures that the resources summary is always included in the comment.
By default, this action will try to authenticate Pulumi with
Pulumi Cloud. If you have not specified a
PULUMI_ACCESS_TOKEN
then you will need to specify an alternative backend via
the cloud-url
argument.
Installation Only
If you want to only install the Pulumi CLI, omit the command
field of the
action.
- uses: pulumi/actions@v5
This will install Pulumi and exit without performing any other operations.
Stack Outputs
Stack outputs are available when using this action. When creating a stack as follows:
package main
import (
random "github.com/pulumi/pulumi-random/sdk/v2/go/random"
"github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
p, err := random.NewRandomPet(ctx, "my-user-name", &random.RandomPetArgs{})
if err != nil {
return err
}
ctx.Export("pet-name", p)
return nil
})
}
We can see that pet-name
is an output. To get the value of this output in the
action, we would use code similar to the following:
- uses: pulumi/actions@v5
id: pulumi
env:
PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_CONFIG_PASSPHRASE }}
with:
command: up
cloud-url: gs://my-bucket
stack-name: org-name/stack-name
- run: echo "My pet name is ${{ steps.pulumi.outputs.pet-name }}"
the pet-name
is available as a named output
Run echo "My pet name is pretty-finch"
Referencing Sensitive Values
We suggest that any sensitive environment variables be referenced using
GitHub Secrets,
and consuming them using
the secrets
attribute
on your workflow's action.
Example workflows
The Pulumi GitHub action uses the Pulumi Automation API in order to coordinate the Pulumi operations. This means that there is no supporting functionality for npm or pip installs. This functionality should be deferred to the correct GitHub Marketplace actions that support it.
- NodeJS Runtime + Pulumi Managed Backend
- Python Runtime + Pulumi Managed Backend
- Go Runtime + Pulumi Managed Backend
- DotNet Runtime + Pulumi Managed Backend
- NodeJS Runtime + AWS S3 Self Managed Backend
- NodeJS Runtime + Google GCS Self Managed Backend
- NodeJS Runtime + Azure Blob Self Managed Backend
- NodeJS Runtime + Local File System Self Managed Backend
Release Cadence
As of v3.18
, we are intending to move to a monthly cadence for minor releases.
Minor releases will be published around the beginning of the month. We may cut a
patch release instead, if the changes are small enough not to warrant a minor
release. We will also cut patch releases periodically as needed to address bugs.
Migrating from v4
v5 of the Pulumi Action updates the NodeJS runtime from Node 16 to Node 20. Users of GitHub Enterprise will have to upgrade to v3.6 or newer. All other users are unaffected.
Migrating from v3
v4 of the Pulumi Action updates the NodeJS runtime from Node 12 to Node 16. Users of GitHub Enterprise will have to upgrade to v3.4 or newer. All other users are unaffected.
Migrating from GitHub Action v1 and v2
Here are some pointers when migrating from v1 to v2 of our GitHub Action.
-
The following inputs have changed from environment variables to action inputs:
PULUMI_ROOT
is nowwork-dir
PULUMI_BACKEND_URL
is nowcloud-url
COMMENT_ON_PR
is nowcomment-on-pr
GITHUB_TOKEN
is nowgithub-token
-
IS_PR_WORKFLOW
is no longer a viable input. The action is able to understand if the workflow is a pull_request due to action type -
The action now runs natively, so the action workflow needs to have the correct environment configured. There are sample workflows available. For examples, if you are running a NodeJS (for example) app then you need to ensure that your action has NodeJS available to it:
- uses: actions/setup-node@v1
with:
node-version: 14.x
- The action will no longer run
npm ci | npm install | pip3 install | pipenv install
. Please ensure that you are installing your dependencies before Pulumi commands are executed, e.g.:
- run: pip install -r requirements
working-directory: infra