Skip to main content
Pulumi logo Pulumi logo
  1. Docs
  2. Delivery
  3. Concepts
  4. Stages and gates

Stages and gates

    Stages give a pipeline its shape. Each stage is a step that a release moves through, commonly one environment such as dev or prod.

    Ordering stages with from

    A stage with no from is an entry stage. Every other stage lists its upstream stages:

    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] });
    
    dev = delivery.Stage("dev", pipeline=pipeline)
    staging = delivery.Stage("staging", pipeline=pipeline, from_=[dev])
    prod = delivery.Stage("prod", pipeline=pipeline, from_=[staging])
    
    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}})
    if err != nil {
    	return err
    }
    
    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 } });
    
    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).build());
    
    resources:
      dev:
        type: delivery:Stage
        properties:
          pipeline: ${pipeline}
      staging:
        type: delivery:Stage
        properties:
          pipeline: ${pipeline}
          from:
            - ${dev}
      prod:
        type: delivery:Stage
        properties:
          pipeline: ${pipeline}
          from:
            - ${staging}
    
    resource "delivery_stage" "dev" {
      pipeline = delivery_pipeline.pipeline
    }
    
    resource "delivery_stage" "staging" {
      pipeline = delivery_pipeline.pipeline
      from     = [delivery_stage.dev]
    }
    
    resource "delivery_stage" "prod" {
      pipeline = delivery_pipeline.pipeline
      from     = [delivery_stage.staging]
    }
    

    A stage with several upstream stages waits until the same release has succeeded in each of them. Stage names must be unique within a pipeline.

    A stage deploys one run at a time. When a newer run reaches a stage while an older run is still waiting for it, or waiting at its gate, the newer run takes its place. A run that has already entered the stage keeps it until it finishes.

    Pulumi Delivery doesn’t detect cycles between stages. A run in a cycle waits until you cancel it.

    Gates

    A gate is a rule on a stage that defines when a pipeline can progress. A release can’t enter the stage until the rule passes.

    Pulumi Delivery supports three kinds of gates, manual, approval, and decision, and you can combine them into one rule. All of them are set in the stage’s when property. Anyone with permission to approve the pipeline’s runs can continue a manual gate. An approval gate names the people or teams who must approve and how many approvals it needs, shows them a preview of the changes, and lets them reject the release. A decision gate has TypeSafe’s Jev model evaluate that preview against questions you write, and rejects the release if the risk is higher than you allow.

    Manual gates

    Manual gates pause the pipeline and wait for a person to continue them. You can use the gate’s description property to help that person decide whether to do so:

    const prod = new delivery.Stage("prod", {
        pipeline,
        from: [staging],
        when: delivery.manual({ description: "Check the staging dashboards first." }),
    });
    
    prod = delivery.Stage(
        "prod",
        pipeline=pipeline,
        from_=[staging],
        when=delivery.RuleArgs(kind="manual", description="Check the staging dashboards first."),
    )
    
    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 the staging dashboards first."),
    	},
    })
    if err != nil {
    	return err
    }
    
    var prod = new Stage("prod", new StageArgs
    {
        Pipeline = pipeline,
        From = { staging },
        When = new RuleArgs { Kind = "manual", Description = "Check the staging dashboards first." },
    });
    
    var prod = new Stage("prod", StageArgs.builder()
        .pipeline(pipeline)
        .from(staging)
        .when(RuleArgs.builder()
            .kind("manual")
            .description("Check the staging dashboards first.")
            .build())
        .build());
    
    resources:
      prod:
        type: delivery:Stage
        properties:
          pipeline: ${pipeline}
          from:
            - ${staging}
          when:
            kind: manual
            description: Check the staging dashboards first.
    
    resource "delivery_stage" "prod" {
      pipeline = delivery_pipeline.pipeline
      from     = [delivery_stage.staging]
      when = {
        kind        = "manual"
        description = "Check the staging dashboards first."
      }
    }
    

    Gates can be continued from the run page in the Pulumi Cloud console or with the REST API. See Continuing a gate with the REST API for details.

    Approval gates

    Approval gates (available in the Pro and Enterprise editions) pause the pipeline until a set number of specified users or team members allow it to continue. List them in approvers as Pulumi usernames or team names, and set count to the number of approvals required (one by default):

    const prod = new delivery.Stage("prod", {
        pipeline,
        from: [staging],
        when: delivery.approval({ approvers: ["platform-leads"], count: 2 }),
    });
    
    prod = delivery.Stage(
        "prod",
        pipeline=pipeline,
        from_=[staging],
        when=delivery.RuleArgs(kind="approval", approvers=["platform-leads"], count=2),
    )
    
    prod, err := delivery.NewStage(ctx, "prod", &delivery.StageArgs{
    	Pipeline: pipeline,
    	From:     delivery.StageArray{staging},
    	When: delivery.RuleArgs{
    		Kind:      pulumi.String("approval"),
    		Approvers: pulumi.StringArray{pulumi.String("platform-leads")},
    		Count:     pulumi.Int(2),
    	},
    })
    if err != nil {
    	return err
    }
    
    var prod = new Stage("prod", new StageArgs
    {
        Pipeline = pipeline,
        From = { staging },
        When = new RuleArgs { Kind = "approval", Approvers = { "platform-leads" }, Count = 2 },
    });
    
    var prod = new Stage("prod", StageArgs.builder()
        .pipeline(pipeline)
        .from(staging)
        .when(RuleArgs.builder()
            .kind("approval")
            .approvers("platform-leads")
            .count(2)
            .build())
        .build());
    
    resources:
      prod:
        type: delivery:Stage
        properties:
          pipeline: ${pipeline}
          from:
            - ${staging}
          when:
            kind: approval
            approvers:
              - platform-leads
            count: 2
    
    resource "delivery_stage" "prod" {
      pipeline = delivery_pipeline.pipeline
      from     = [delivery_stage.staging]
      when = {
        kind      = "approval"
        approvers = ["platform-leads"]
        count     = 2
      }
    }
    

    Before approving, an approver sees a preview of the stack updates the stage will make. The preview doesn’t cover jobs, because they run arbitrary commands. It can also be incomplete: a stack whose preview shows “Not available” might still change when the stage runs.

    Decision gates

    This Pulumi Cloud feature is available in the Pro and Enterprise editions.

    A decision gate evaluates whether a release can enter a stage based on the risk tolerance you define. It uses TypeSafe’s Jev model to answer a set of yes-or-no questions about the stage’s preview, and for each question, you set the highest risk you’ll accept that the answer is yes. If any answer is riskier than you allow, the gate rejects the release and the run fails.

    A decision gate evaluates only the preview of the stack updates the stage will make, so the stage needs at least one Stacks resource. Jobs, artifacts, and agent responses aren’t part of the preview. Delivery gives the preview to Jev automatically.

    For example, this gate stops a release if Jev thinks the prod stack updates delete a database:

    const prod = new delivery.Stage("prod", {
        pipeline,
        from: [staging],
        when: delivery.decision({
            questions: {
                dataLoss: {
                    instructions: "Does the preview delete or replace a database or storage bucket?",
                    maximumRisk: 0.05,
                },
            },
        }),
    });
    
    new delivery.Stacks("prodServices", {
        stage: prod,
        stacks: {
            api: { stack: "shop-api/prod", source: repo, directory: "api" },
        },
    });
    
    prod = delivery.Stage(
        "prod",
        pipeline=pipeline,
        from_=[staging],
        when=delivery.RuleArgs(
            kind="decision",
            questions={
                "dataLoss": delivery.DecisionQuestionArgs(
                    instructions="Does the preview delete or replace a database or storage bucket?",
                    maximum_risk=0.05,
                ),
            },
        ),
    )
    
    delivery.Stacks(
        "prodServices",
        stage=prod,
        stacks={
            "api": {"stack": "shop-api/prod", "source": repo, "directory": "api"},
        },
    )
    
    prod, err := delivery.NewStage(ctx, "prod", &delivery.StageArgs{
    	Pipeline: pipeline,
    	From:     delivery.StageArray{staging},
    	When: delivery.RuleArgs{
    		Kind: pulumi.String("decision"),
    		Questions: delivery.DecisionQuestionMap{
    			"dataLoss": delivery.DecisionQuestionArgs{
    				Instructions: pulumi.String("Does the preview delete or replace a database or storage bucket?"),
    				MaximumRisk:  pulumi.Float64(0.05),
    			},
    		},
    	},
    })
    if err != nil {
    	return err
    }
    
    _, err = delivery.NewStacks(ctx, "prodServices", &delivery.StacksArgs{
    	Stage: prod,
    	Stacks: delivery.StacksEntryMap{
    		"api": delivery.StacksEntryArgs{Stack: pulumi.String("shop-api/prod"), Source: repo, Directory: pulumi.String("api")},
    	},
    })
    if err != nil {
    	return err
    }
    
    var prod = new Stage("prod", new StageArgs
    {
        Pipeline = pipeline,
        From = { staging },
        When = new RuleArgs
        {
            Kind = "decision",
            Questions =
            {
                ["dataLoss"] = new DecisionQuestionArgs
                {
                    Instructions = "Does the preview delete or replace a database or storage bucket?",
                    MaximumRisk = 0.05,
                },
            },
        },
    });
    
    new Stacks("prodServices", new StacksArgs
    {
        Stage = prod,
        Stacks =
        {
            ["api"] = new StacksEntryArgs { Stack = "shop-api/prod", Source = repo, Directory = "api" },
        },
    });
    
    var prod = new Stage("prod", StageArgs.builder()
        .pipeline(pipeline)
        .from(staging)
        .when(RuleArgs.builder()
            .kind("decision")
            .questions(Map.of("dataLoss", DecisionQuestionArgs.builder()
                .instructions("Does the preview delete or replace a database or storage bucket?")
                .maximumRisk(0.05)
                .build()))
            .build())
        .build());
    
    new Stacks("prodServices", StacksArgs.builder()
        .stage(prod)
        .stacks(Map.of(
            "api", StacksEntryArgs.builder().stack("shop-api/prod").source(repo).directory("api").build()))
        .build());
    
    resources:
      prod:
        type: delivery:Stage
        properties:
          pipeline: ${pipeline}
          from:
            - ${staging}
          when:
            kind: decision
            questions:
              dataLoss:
                instructions: Does the preview delete or replace a database or storage bucket?
                maximumRisk: 0.05
      prodServices:
        type: delivery:Stacks
        properties:
          stage: ${prod}
          stacks:
            api:
              stack: shop-api/prod
              source: ${repo}
              directory: api
    
    resource "delivery_stage" "prod" {
      pipeline = delivery_pipeline.pipeline
      from     = [delivery_stage.staging]
      when = {
        kind = "decision"
        questions = {
          dataLoss = {
            instructions = "Does the preview delete or replace a database or storage bucket?"
            maximum_risk = 0.05
          }
        }
      }
    }
    
    resource "delivery_stacks" "prodServices" {
      stage = delivery_stage.prod
      stacks = {
        api = {
          stack     = "shop-api/prod"
          source    = delivery_git_hub_source.repo
          directory = "api"
        }
      }
    }
    

    For each question, Jev estimates the probability that the answer is yes. Delivery compares that estimate with the question’s maximumRisk, a number from 0 to 1, and the gate passes only when every question is at or below its threshold.

    If the stage’s preview is larger than Jev’s context window, the gate rejects the release and the run fails.

    Combining rules

    You can also build composite rules that combine manual, approval, and decision gates. In the following example, the pipeline is paused until <your-colleague> approves and someone continues the dashboards check:

    const prod = new delivery.Stage("prod", {
        pipeline,
        from: [staging],
        when: delivery.allOfOutput({
            rules: [
                delivery.approvalOutput({ approvers: ["<your-colleague>"] }),
                delivery.manualOutput({ name: "dashboards", description: "Check the dashboards first." }),
            ],
        }),
    });
    
    prod = delivery.Stage(
        "prod",
        pipeline=pipeline,
        from_=[staging],
        when=delivery.RuleArgs(
            kind="all",
            rules=[
                delivery.RuleArgs(kind="approval", approvers=["<your-colleague>"]),
                delivery.RuleArgs(kind="manual", name="dashboards", description="Check the dashboards first."),
            ],
        ),
    )
    
    prod, err := delivery.NewStage(ctx, "prod", &delivery.StageArgs{
    	Pipeline: pipeline,
    	From:     delivery.StageArray{staging},
    	When: delivery.RuleArgs{
    		Kind: pulumi.String("all"),
    		Rules: delivery.RuleArray{
    			delivery.RuleArgs{
    				Kind:      pulumi.String("approval"),
    				Approvers: pulumi.StringArray{pulumi.String("<your-colleague>")},
    			},
    			delivery.RuleArgs{
    				Kind:        pulumi.String("manual"),
    				Name:        pulumi.String("dashboards"),
    				Description: pulumi.String("Check the dashboards first."),
    			},
    		},
    	},
    })
    if err != nil {
    	return err
    }
    
    var prod = new Stage("prod", new StageArgs
    {
        Pipeline = pipeline,
        From = { staging },
        When = new RuleArgs
        {
            Kind = "all",
            Rules =
            {
                new RuleArgs { Kind = "approval", Approvers = { "<your-colleague>" } },
                new RuleArgs { Kind = "manual", Name = "dashboards", Description = "Check the dashboards first." },
            },
        },
    });
    
    var prod = new Stage("prod", StageArgs.builder()
        .pipeline(pipeline)
        .from(staging)
        .when(RuleArgs.builder()
            .kind("all")
            .rules(
                RuleArgs.builder()
                    .kind("approval")
                    .approvers("<your-colleague>")
                    .build(),
                RuleArgs.builder()
                    .kind("manual")
                    .name("dashboards")
                    .description("Check the dashboards first.")
                    .build())
            .build())
        .build());
    
    resources:
      prod:
        type: delivery:Stage
        properties:
          pipeline: ${pipeline}
          from:
            - ${staging}
          when:
            kind: all
            rules:
              - kind: approval
                approvers:
                  - <your-colleague>
              - kind: manual
                name: dashboards
                description: Check the dashboards first.
    
    resource "delivery_stage" "prod" {
      pipeline = delivery_pipeline.pipeline
      from     = [delivery_stage.staging]
      when = {
        kind = "all"
        rules = [
          {
            kind      = "approval"
            approvers = ["<your-colleague>"]
          },
          {
            kind        = "manual"
            name        = "dashboards"
            description = "Check the dashboards first."
          },
        ]
      }
    }
    

    Composite rules can be of type all or any. all-type rules require that every rule in the rules list be satisfied, as in the previous example. any-type rules require at least one of them to be. You can nest rules up to three levels deep, counting the rules themselves: an all rule that contains an any rule that contains an approval is the deepest a gate can go.

    Every rule takes an optional name, and names must be unique within a gate. An approval rule’s name defaults to approval and a manual rule’s to manual, so name each rule when a gate has two of the same kind.

    Continuing a gate with the REST API

    Any credential with write access to the pipeline stack can continue a manual gate. To do it from another system, such as a deployment hook:

    1. Read the run with GET /api/preview/stacks/<org>/<project>/<stack>/delivery/runs/<run-number>.

    2. In stages, find the stage. If stages[].gate.status is open, note stages[].gate.id.

    3. Send POST .../delivery/runs/<run-number>/gates/<gate-id>/continue with a JSON body:

      curl -X POST \
          -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{}' \
          https://api.pulumi.com/api/preview/stacks/acme/shop-delivery/main/delivery/runs/<run-number>/gates/<gate-id>/continue
      

    A gate with one manual rule takes an empty JSON object. For a gate with several manual rules, pass the rule’s name in condition, as in {"condition": "dashboards"}.

    Artifacts

    Artifacts are to pipelines what stack outputs are to stacks. An artifact is a named value that a stage publishes once the release reaches it, such as a cluster endpoint, a database ID, or a container image tag. Other pipelines in your organization read it with a PipelineSource. Artifacts are how one pipeline hands values to another without either one reaching into the other’s stacks.

    Publishing an artifact

    An Artifact resource names the stage that publishes it:

    new delivery.Artifact("clusterEndpoint", {
        stage: prod,
        value: cluster.outputs.apply(o => o["cluster"]["endpoint"]),
    });
    
    delivery.Artifact(
        "clusterEndpoint",
        stage=prod,
        value=cluster.outputs.apply(lambda o: o["cluster"]["endpoint"]),
    )
    
    _, err = delivery.NewArtifact(ctx, "clusterEndpoint", &delivery.ArtifactArgs{
    	Stage: prod,
    	Value: cluster.Outputs.ApplyT(func(o map[string]map[string]interface{}) interface{} {
    		return o["cluster"]["endpoint"]
    	}),
    })
    if err != nil {
    	return err
    }
    
    new Artifact("clusterEndpoint", new ArtifactArgs
    {
        Stage = prod,
        Value = cluster.Outputs.Apply(o => o["cluster"]["endpoint"]),
    });
    
    new Artifact("clusterEndpoint", ArtifactArgs.builder()
        .stage(prod)
        .value(cluster.outputs().applyValue(o -> (Object) o.get("cluster").get("endpoint")))
        .build());
    
    resources:
      clusterEndpoint:
        type: delivery:Artifact
        properties:
          stage: ${prod}
          value: ${cluster.outputs["cluster"]["endpoint"]}
    
    resource "delivery_artifact" "clusterEndpoint" {
      stage = delivery_stage.prod
      value = delivery_stacks.cluster.outputs["cluster"]["endpoint"]
    }
    

    The value can be any structured value, such as a string, number, list, or map, and it can be secret. An artifact can’t hold a file or binary data. It usually comes from the outputs of a stack update or a job in the same stage, as in this example, where cluster is a Stacks resource.

    Other pipelines see an artifact once the release reaches its stage and the value is known. Because it belongs to a stage, a downstream pipeline that reads the prod stage only ever sees values from releases that prod deployed.

    Reading artifacts from other pipelines

    A downstream pipeline can read an upstream pipeline’s artifacts through a PipelineSource:

    const platform = new delivery.PipelineSource("platform", {
        pipeline: "platform-delivery/main",
        stage: "prod",
        trigger: true,
    });
    
    const clusterEndpoint = platform.artifacts["clusterEndpoint"];
    
    platform = delivery.PipelineSource(
        "platform",
        pipeline="platform-delivery/main",
        stage="prod",
        trigger=True,
    )
    
    cluster_endpoint = platform.artifacts["clusterEndpoint"]
    
    platform, err := delivery.NewPipelineSource(ctx, "platform", &delivery.PipelineSourceArgs{
    	Pipeline: pulumi.String("platform-delivery/main"),
    	Stage:    pulumi.String("prod"),
    	Trigger:  pulumi.Bool(true),
    })
    if err != nil {
    	return err
    }
    
    clusterEndpoint := platform.Artifacts.MapIndex(pulumi.String("clusterEndpoint"))
    
    var platform = new PipelineSource("platform", new PipelineSourceArgs
    {
        Pipeline = "platform-delivery/main",
        Stage = "prod",
        Trigger = true,
    });
    
    var clusterEndpoint = platform.Artifacts.Apply(artifacts => artifacts["clusterEndpoint"]);
    
    var platform = new PipelineSource("platform", PipelineSourceArgs.builder()
        .pipeline("platform-delivery/main")
        .stage("prod")
        .trigger(true)
        .build());
    
    var clusterEndpoint = platform.artifacts().applyValue(artifacts -> artifacts.get("clusterEndpoint"));
    
    resources:
      platform:
        type: delivery:PipelineSource
        properties:
          pipeline: platform-delivery/main
          stage: prod
          trigger: true
    
    variables:
      clusterEndpoint: ${platform.artifacts["clusterEndpoint"]}
    
    resource "delivery_pipeline_source" "platform" {
      pipeline = "platform-delivery/main"
      stage    = "prod"
      trigger  = true
    }
    
    locals {
      cluster_endpoint = delivery_pipeline_source.platform.artifacts["clusterEndpoint"]
    }
    

    Pipeline sources return the artifacts of the latest release the specified stage deployed, including the artifacts that earlier stages published for that release.

    Secret artifacts

    If any artifact is secret, the whole artifacts map is secret. A Stacks entry’s config rejects secret values, so pass a secret artifact to a stack update or job in environment instead.

    Next steps

      The infrastructure platform for humans and agents.