Skip to main content
Pulumi logo Pulumi logo
  1. Docs
  2. Delivery
  3. Get started

Get started with Pulumi Delivery

    In this guide, you’ll write a pipeline that deploys an app through three environments, dev, staging, and prod, and pauses before prod until you tell it to continue. You’ll register the pipeline with Pulumi Cloud, push a commit, and watch the release move through each stage. From then on, every push to main starts a new run.

    Pulumi Delivery is in public preview. Behavior, the SDK, and the REST API routes under /api/preview/ can change before general availability.

    Before you begin

    You’ll need:

    • A Pulumi Cloud organization on any edition
    • Pulumi CLI v3.277.0 or later.
    • A GitHub repository you can push to, with the GitHub integration installed for your organization and given access to that repository.
    • The toolchain for the language you’ll write the pipeline in, such as Node.js for TypeScript

    This guide uses a repository named acme/shop on the main branch. Replace acme/shop with your own repository as you go.

    Lay out the repository

    The pipeline program and the project it deploys live side by side in the same repository:

    app/        the project the pipeline deploys
    delivery/   the pipeline program
    

    Create the app stacks

    Delivery updates existing stacks but doesn’t create them, so you’ll create one stack for each environment first. To keep the focus on the pipeline, the app project doesn’t create any cloud resources. It only returns a URL built from the stack name. Create app/Pulumi.yaml:

    name: shop-app
    runtime: yaml
    outputs:
      url: https://${pulumi.stack}.shop.example.com
    

    Then create a dev, staging, and prod stack for the project:

    cd app
    pulumi stack init dev
    pulumi stack init staging
    pulumi stack init prod
    cd ..
    

    Because the project creates no resources, Delivery doesn’t need any cloud credentials to deploy it. When you’re ready to deploy real infrastructure, see Cloud credentials.

    Write the pipeline program

    The pipeline program is a Pulumi project of its own, written in any Pulumi language. Create it in the delivery directory along with its stack, main:

    mkdir delivery && cd delivery
    pulumi new typescript --name shop-delivery --stack main --yes
    pulumi package add delivery
    
    mkdir delivery && cd delivery
    pulumi new python --name shop-delivery --stack main --yes
    pulumi package add delivery
    
    mkdir delivery && cd delivery
    pulumi new go --name shop-delivery --stack main --yes
    pulumi package add delivery
    
    mkdir delivery && cd delivery
    pulumi new csharp --name shop-delivery --stack main --yes
    pulumi package add delivery
    
    mkdir delivery && cd delivery
    pulumi new java --name shop-delivery --stack main --yes
    pulumi package add delivery
    
    mkdir delivery && cd delivery
    pulumi new yaml --name shop-delivery --stack main --yes
    pulumi package add delivery
    

    Create delivery/Pulumi.yaml with the HCL runtime:

    name: shop-delivery
    runtime: hcl
    

    Then create the pipeline stack:

    cd delivery
    pulumi stack init main
    

    pulumi package add delivery writes a packages entry to Pulumi.yaml. Keep that entry, because Pulumi Cloud reads it to install the Delivery SDK for each run.

    Now replace the program that pulumi new created with the pipeline. The program declares the repository as a source, three stages in order, and the app stack each stage updates:

    In index.ts:

    import * as delivery from "@pulumi/delivery";
    
    const repo = new delivery.GitHubSource("repo", {
        repository: "acme/shop",
        branch: "main",
        trigger: true,
    });
    
    const pipeline = new delivery.Pipeline("shop");
    
    const dev = new delivery.Stage("dev", { pipeline });
    const staging = new delivery.Stage("staging", { pipeline, from: [dev] });
    const prod = new delivery.Stage("prod", {
        pipeline,
        from: [staging],
        when: delivery.manual({ description: "Check staging before you ship to prod." }),
    });
    
    for (const [env, stage] of Object.entries({ dev, staging, prod })) {
        new delivery.Stacks(env, {
            stage,
            stacks: {
                app: { stack: `shop-app/${env}`, source: repo, directory: "app" },
            },
        });
    }
    

    In __main__.py:

    import pulumi_delivery as delivery
    
    repo = delivery.GitHubSource(
        "repo", repository="acme/shop", branch="main", trigger=True
    )
    
    pipeline = delivery.Pipeline("shop")
    
    dev = delivery.Stage("dev", pipeline=pipeline)
    staging = delivery.Stage("staging", pipeline=pipeline, from_=[dev])
    prod = delivery.Stage(
        "prod",
        pipeline=pipeline,
        from_=[staging],
        when=delivery.RuleArgs(kind="manual", description="Check staging before you ship to prod."),
    )
    
    for env, stage in {"dev": dev, "staging": staging, "prod": prod}.items():
        delivery.Stacks(
            env,
            stage=stage,
            stacks={
                "app": {"stack": f"shop-app/{env}", "source": repo, "directory": "app"},
            },
        )
    

    In main.go:

    package main
    
    import (
    	"github.com/pulumi/pulumi-delivery/sdk/go/delivery"
    	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
    )
    
    func main() {
    	pulumi.Run(func(ctx *pulumi.Context) error {
    		repo, err := delivery.NewGitHubSource(ctx, "repo", &delivery.GitHubSourceArgs{
    			Repository: pulumi.String("acme/shop"),
    			Branch:     pulumi.String("main"),
    			Trigger:    pulumi.Bool(true),
    		})
    		if err != nil {
    			return err
    		}
    
    		pipeline, err := delivery.NewPipeline(ctx, "shop", nil)
    		if err != nil {
    			return err
    		}
    
    		dev, err := delivery.NewStage(ctx, "dev", &delivery.StageArgs{Pipeline: pipeline})
    		if err != nil {
    			return err
    		}
    		staging, err := delivery.NewStage(ctx, "staging", &delivery.StageArgs{
    			Pipeline: pipeline,
    			From:     delivery.StageArray{dev},
    		})
    		if err != nil {
    			return err
    		}
    		prod, err := delivery.NewStage(ctx, "prod", &delivery.StageArgs{
    			Pipeline: pipeline,
    			From:     delivery.StageArray{staging},
    			When: delivery.RuleArgs{
    				Kind:        pulumi.String("manual"),
    				Description: pulumi.String("Check staging before you ship to prod."),
    			},
    		})
    		if err != nil {
    			return err
    		}
    
    		for env, stage := range map[string]*delivery.Stage{"dev": dev, "staging": staging, "prod": prod} {
    			_, err := delivery.NewStacks(ctx, env, &delivery.StacksArgs{
    				Stage: stage,
    				Stacks: delivery.StacksEntryMap{
    					"app": delivery.StacksEntryArgs{Stack: pulumi.String("shop-app/" + env), Source: repo, Directory: pulumi.String("app")},
    				},
    			})
    			if err != nil {
    				return err
    			}
    		}
    		return nil
    	})
    }
    

    In Program.cs:

    using System.Collections.Generic;
    using Pulumi;
    using Pulumi.Delivery.Delivery;
    using Pulumi.Delivery.Delivery.Inputs;
    
    return await Deployment.RunAsync(() =>
    {
        var repo = new GitHubSource("repo", new GitHubSourceArgs
        {
            Repository = "acme/shop",
            Branch = "main",
            Trigger = true,
        });
    
        var pipeline = new Pipeline("shop");
    
        var dev = new Stage("dev", new StageArgs { Pipeline = pipeline });
        var staging = new Stage("staging", new StageArgs { Pipeline = pipeline, From = { dev } });
        var prod = new Stage("prod", new StageArgs
        {
            Pipeline = pipeline,
            From = { staging },
            When = new RuleArgs { Kind = "manual", Description = "Check staging before you ship to prod." },
        });
    
        var stages = new Dictionary<string, Stage> { ["dev"] = dev, ["staging"] = staging, ["prod"] = prod };
        foreach (var (env, stage) in stages)
        {
            new Stacks(env, new StacksArgs
            {
                Stage = stage,
                Stacks =
                {
                    ["app"] = new StacksEntryArgs { Stack = $"shop-app/{env}", Source = repo, Directory = "app" },
                },
            });
        }
    });
    

    In src/main/java/myproject/App.java:

    package myproject;
    
    import com.pulumi.Pulumi;
    import com.pulumi.delivery.delivery.*;
    import com.pulumi.delivery.delivery.inputs.*;
    import java.util.Map;
    
    public class App {
        public static void main(String[] args) {
            Pulumi.run(ctx -> {
                var repo = new GitHubSource("repo", GitHubSourceArgs.builder()
                    .repository("acme/shop")
                    .branch("main")
                    .trigger(true)
                    .build());
    
                var pipeline = new Pipeline("shop");
    
                var dev = new Stage("dev", StageArgs.builder().pipeline(pipeline).build());
                var staging = new Stage("staging", StageArgs.builder().pipeline(pipeline).from(dev).build());
                var prod = new Stage("prod", StageArgs.builder()
                    .pipeline(pipeline)
                    .from(staging)
                    .when(RuleArgs.builder()
                        .kind("manual")
                        .description("Check staging before you ship to prod.")
                        .build())
                    .build());
    
                Map.of("dev", dev, "staging", staging, "prod", prod).forEach((env, stage) ->
                    new Stacks(env, StacksArgs.builder()
                        .stage(stage)
                        .stacks(Map.of(
                            "app", StacksEntryArgs.builder().stack("shop-app/" + env).source(repo).directory("app").build()))
                        .build()));
            });
        }
    }
    

    In Pulumi.yaml, keep the packages entry and replace the rest with:

    name: shop-delivery
    runtime: yaml
    
    resources:
      repo:
        type: delivery:GitHubSource
        properties:
          repository: acme/shop
          branch: main
          trigger: true
      shop:
        type: delivery:Pipeline
    
      dev:
        type: delivery:Stage
        properties:
          pipeline: ${shop}
      staging:
        type: delivery:Stage
        properties:
          pipeline: ${shop}
          from:
            - ${dev}
      prod:
        type: delivery:Stage
        properties:
          pipeline: ${shop}
          from:
            - ${staging}
          when:
            kind: manual
            description: Check staging before you ship to prod.
    
      devStacks:
        type: delivery:Stacks
        properties:
          stage: ${dev}
          stacks:
            app: { stack: shop-app/dev, source: "${repo}", directory: app }
      stagingStacks:
        type: delivery:Stacks
        properties:
          stage: ${staging}
          stacks:
            app: { stack: shop-app/staging, source: "${repo}", directory: app }
      prodStacks:
        type: delivery:Stacks
        properties:
          stage: ${prod}
          stacks:
            app: { stack: shop-app/prod, source: "${repo}", directory: app }
    

    In main.tf:

    terraform {
      required_providers {
        delivery = {
          source = "pulumi/delivery"
        }
      }
    }
    
    resource "delivery_git_hub_source" "repo" {
      repository = "acme/shop"
      branch     = "main"
      trigger    = true
    }
    
    resource "delivery_pipeline" "shop" {}
    
    resource "delivery_stage" "dev" {
      pipeline = delivery_pipeline.shop
    }
    
    resource "delivery_stage" "staging" {
      pipeline = delivery_pipeline.shop
      from     = [delivery_stage.dev]
    }
    
    resource "delivery_stage" "prod" {
      pipeline = delivery_pipeline.shop
      from     = [delivery_stage.staging]
      when = {
        kind        = "manual"
        description = "Check staging before you ship to prod."
      }
    }
    
    locals {
      environments = {
        dev     = delivery_stage.dev
        staging = delivery_stage.staging
        prod    = delivery_stage.prod
      }
    }
    
    resource "delivery_stacks" "env" {
      for_each = local.environments
      stage    = each.value
      stacks = {
        app = { stack = "shop-app/${each.key}", source = delivery_git_hub_source.repo, directory = "app" }
      }
    }
    

    Here’s what each part does:

    • The GitHubSource points at main in your repository. Setting trigger to true starts a run on every push to main.
    • The Pipeline resource declares the pipeline. A pipeline program declares exactly one.
    • The three Stage resources run in order, because each one lists the stage before it in from. The prod stage also has a manual gate in when, so a release waits there until someone continues it.
    • The loop adds a Stacks resource to each stage, which runs pulumi up on that environment’s shop-app stack.

    Register the pipeline

    Register the pipeline from the delivery directory:

    pulumi delivery register
    

    Registering tells Pulumi Cloud about the pipeline and writes the program’s location in your repository to the delivery:source setting in Pulumi.main.yaml. It doesn’t start a run, so the output lists each stage as waiting for one. Commit everything, including that config file, and push:

    cd ..
    git add app delivery
    git commit -m "Add the shop delivery pipeline"
    git push origin main
    

    The push matches the source’s trigger, so it starts your first run.

    Watch the release

    In the Pulumi Cloud console, navigate to Delivery > Pipelines and select shop-delivery/main. Your run is listed under In progress. Select it to open the run page.

    The dev stage updates shop-app/dev, and once it succeeds, staging updates shop-app/staging. The run then pauses at the manual gate in front of prod, and its status reads “Waiting for someone to continue at prod”.

    In the run graph, select the Manual gate before prod. It shows the description you gave it. Select Continue, and Delivery updates shop-app/prod. Once the run finishes, open any of the three shop-app stacks to see the update the pipeline ran and the url output for that environment.

    That’s your first release. Every push to main from now on starts a new run, pinned to that commit, so the code that passed staging is the code that reaches prod.

    Next steps

      The infrastructure platform for humans and agents.