Skip to main content
  1. Docs
  2. Infrastructure as Code
  3. Guides
  4. Continuous Delivery
  5. Adding CI/CD support

Adding Pulumi support for CI/CD systems

    If the Pulumi CLI doesn’t automatically detect your CI/CD system, this guide walks you through how you can configure your CI/CD environment manually to surface data in Pulumi Cloud.

    Overview

    The Pulumi CLI already supports enhanced metadata for several popular CI/CD systems. We have tried to make it easy for contributors to add/update support for CI systems. This document walks-through how you can modify the Pulumi CLI to support your own CI system or perhaps even update an existing one.

    The detection of metadata in a CI environment depends on some key environment variables that a CI system injects into the build environment of their build agents. The Pulumi CLI uses those environment variables to try and determine the values for the following properties:

    • CI System Name
    • Build ID
    • Build Number
    • Build Type
    • Build URL
    • Commit SHA
    • Branch Name
    • Commit Message
    • PR Number

    The metadata about your CI environment is displayed in the Pulumi Cloud stack activity log. The metadata from your CI environment and the information about your Git repository allow Pulumi to provide links to pull requests and commits.

    Stack update entry

    In order to add support for your CI system, you should be somewhat familiar in working with Go.

    How does it work?

    There are 2 parts to the CLI for it to be able to correctly detect the environment variables of a CI system.

    1. Detecting in which CI system the Pulumi CLI is currently running
    2. Detecting additional environment variables for a specific CI system

    In the pulumi/pulumi repo the sdk/go/common/util/ciutil package contains all of the logic necessary for the above. Every stack preview or update calls the functions exported from this package.

    Detecting the CI system

    • Add an entry to the detectors slice in detect.go where all of the CI systems are registered.
    • When you add the entry, you have two options, either use the baseCI as the CI System implementation or add a specific implementation that overrides the DetectVars function. More on this later in the next section.

    For example, here’s the AppVeyor entry.

    baseCI{
    Name:            AppVeyor,
    EnvVarsToDetect: []string{"APPVEYOR"},
},

    The EnvVarsToDetect is used by the IsCI() method in systems.go, which iterates through the environment variables that a certain CI system is known to set in its build agents. Some CI systems set specific values in certain environment variables, and in such cases you should use EnvValuesToDetect. An example for the latter is Codeship. See its entry in the detectors slice.

    Detecting additional metadata about a CI build

    A CI build could have been triggered by a PR or a push build. In this case, the linked PR number is useful so that Pulumi Cloud can link to it. Note that the detection is done on a best-effort basis. We support linking to the following Git-based version control systems:

    • Atlassian Bitbucket
    • Azure DevOps
    • GitHub
    • GitLab

    All of the above source control systems have a concept of a PR, and PR builds, as well as push builds.

    • Add a new file to the sdk/go/common/util/ciutil folder with the name of the CI system for which you are adding support.
    • Define a new struct for the CI system and embed baseCI in its definition. Refer to any of the pre-existing implementations, such as the travis.go file.
    • Implement the DetectVars() function. This is the function where you should construct a new instance of the Vars struct and set its properties accordingly.

    That’s it! Send us a new PR in the pulumi/pulumi repo with your addition. We would love to help you get that merged as soon as possible.

    Using a fallback

    If the CI system you are using is not currently detected by Pulumi, you can set the PULUMI_CI_SYSTEM environment variable. Then the following environment variables can be used to surface CI system metadata for an update.

    • PULUMI_CI_SYSTEM
    • PULUMI_CI_BRANCH_NAME
    • PULUMI_CI_BUILD_ID
    • PULUMI_CI_BUILD_NUMBER
    • PULUMI_CI_BUILD_TYPE
    • PULUMI_CI_BUILD_URL
    • PULUMI_CI_PULL_REQUEST_SHA
    • PULUMI_COMMIT_MESSAGE
    • PULUMI_PR_NUMBER

    You can also find these variables in the generic.go file in the sdk/go/common/util/ciutil folder.

    PULUMI_CI_BRANCH_NAME and PULUMI_COMMIT_MESSAGE are treated as fallbacks rather than overrides. When the Pulumi CLI runs inside a Git repository with a normal (non-detached) HEAD and a non-empty commit message, the values read from Git win and these two environment variables are ignored. They take effect when:

    • The Git working tree is in a detached-HEAD state (common on CI runners that check out a commit SHA), or
    • The build runs against a Mercurial repository (in which case the CI branch name overrides the hg branch), or
    • No repository is detected at all and the corresponding PULUMI_GIT_HEAD_NAME / PULUMI_GIT_COMMIT_MESSAGE variables are not set.

    The other PULUMI_CI_* variables (build ID, build number, build type, build URL, PR SHA, PR number) are applied whenever they are set.