aws-delivlib/lib/pipeline.d.ts

A fabulous library for defining continuous pipelines for building, testing and releasing code libraries.

import { Duration, aws_cloudwatch as cloudwatch, aws_codebuild as cbuild, aws_codepipeline as cpipeline, aws_codepipeline_actions as cpipeline_actions, aws_iam as iam, aws_s3 as s3 } from 'aws-cdk-lib';
import { Construct, IConstruct } from 'constructs';
import { AutoBuild, AutoBuildOptions } from './auto-build';
import { Canary, CanaryProps } from './canary';
import { ChangeController } from './change-controller';
import * as publishing from './publishing';
import { AutoBump, AutoBumpProps } from './pull-request';
import { AutoMergeBackPipelineOptions } from './pull-request/merge-back';
import { IRepo } from './repo';
import { Shellable, ShellableProps } from './shellable';
import * as signing from './signing';
export interface PipelineProps {
    /**
     * The source repository to build (e.g. GitHubRepo).
     */
    readonly repo: IRepo;
    /**
     * A display name for this pipeline.
     */
    readonly title?: string;
    /**
     * A physical name for this pipeline.
     * @default - a new name will be generated.
     */
    readonly pipelineName?: string;
    /**
     * Branch to build.
     * @default master
     */
    readonly branch?: string;
    /**
     * Email to send failure notifications.
     * @default - No email notifications
     */
    readonly notificationEmail?: string;
    /**
     * The image used for the builds.
     *
     * @default jsii/superchain (see docs)
     */
    readonly buildImage?: cbuild.IBuildImage;
    /**
     * The name of the CodeBuild project that will be part of this pipeline.
     * @default - `${pipelineName}-Build`, if `pipelineName` property is specified; automatically generated, otherwise.
     */
    readonly buildProjectName?: string;
    /**
     * The type of compute to use for this build.
     * See the {@link ComputeType} enum for the possible values.
     *
     * @default taken from {@link #buildImage#defaultComputeType}
     */
    readonly computeType?: cbuild.ComputeType;
    /**
     * Indicates how the project builds Docker images. Specify true to enable
     * running the Docker daemon inside a Docker container. This value must be
     * set to true only if this build project will be used to build Docker
     * images, and the specified build environment image is not one provided by
     * AWS CodeBuild with Docker support. Otherwise, all associated builds that
     * attempt to interact with the Docker daemon will fail.
     *
     * @default false
     */
    readonly privileged?: boolean;
    /**
     * Environment variables to pass to build
     */
    readonly environment?: {
        [key: string]: string;
    };
    /**
     * Optional buildspec, as an alternative to a buildspec.yml file
     */
    readonly buildSpec?: cbuild.BuildSpec;
    /**
     * Indicates whether to re-run the pipeline after you've updated it.
     * @default true
     */
    readonly restartExecutionOnUpdate?: boolean;
    /**
     * Indicates the concurrency limit test and publish stages.
     *
     * For example, if this value is 2, then only two actions will execute concurrently.
     * If this value is 1, the pipeline will not have any concurrent execution.
     *
     * @default - no limit
     */
    readonly concurrency?: number;
    /**
     * Set the default dryRun for all publishing steps
     *
     * (Can still be changed when adding a step).
     *
     * @default false
     */
    readonly dryRun?: boolean;
    /**
     * Automatically build commits that are pushed to this repository, including PR builds on github.
     *
     * @default false
     */
    readonly autoBuild?: boolean;
    /**
     * Options for auto-build
     *
     * @default - 'autoBuildOptions.publicLogs' will be set to its default. 'autoBuildOptions.buildspec' will be configured to match with the
     * 'buildSpec' property.
     */
    readonly autoBuildOptions?: AutoBuildOptions;
    /**
     * Post a notification to the given Chime webhooks if the pipeline fails
     * @default - no Chime notifications on pipeline failure
     * @deprecated - use `notifyOnFailure()` instead in combination with `PipelineNotification.chime()`.
     */
    readonly chimeFailureWebhooks?: string[];
    /**
     * The Chime message to post
     *
     * @default - A default message
     */
    readonly chimeMessage?: string;
    /**
     * Build timeout
     *
     * How long the build can take at maximum (before failing with an error).
     *
     * @default - Duration.hours(8)
     */
    readonly buildTimeout?: Duration;
}
export interface PipelineNotificationBindOptions {
    readonly pipeline: Pipeline;
}
export interface IPipelineNotification {
    bind(pipeline: PipelineNotificationBindOptions): void;
}
/**
 * Options for configuring an auto bump for this pipeline.
 */
export interface AutoBumpOptions extends Omit<AutoBumpProps, 'repo'> {
}
/**
 * Defines a delivlib CI/CD pipeline.
 */
export declare class Pipeline extends Construct {
    buildRole?: iam.IRole;
    readonly failureAlarm: cloudwatch.Alarm;
    readonly buildOutput: cpipeline.Artifact;
    readonly sourceArtifact: cpipeline.Artifact;
    /**
     * The primary CodeBuild project of this pipeline.
     */
    readonly buildProject: cbuild.IProject;
    /**
     * The auto build project. undefined if 'autoBuild' is disabled for this pipeline.
     */
    readonly autoBuildProject?: cbuild.Project;
    readonly pipeline: cpipeline.Pipeline;
    private readonly branch;
    private readonly notify?;
    private defaultArtifact;
    private stages;
    private _signingOutput?;
    private readonly concurrency?;
    private readonly repo;
    private readonly dryRun;
    private readonly buildEnvironment;
    private readonly buildSpec?;
    private firstPublishStageName?;
    private readonly descrPipelineName;
    constructor(parent: Construct, name: string, props: PipelineProps);
    /**
     * Signing output artifact
     */
    get signingOutput(): cpipeline.Artifact | undefined;
    notifyOnFailure(notification: IPipelineNotification): void;
    /**
     * Add an action to run a shell script to the pipeline
     *
     * @return The Shellable and the Action added to the pipeline.
     */
    addShellable(stageName: string, id: string, options: AddShellableOptions): {
        shellable: Shellable;
        action: cpipeline_actions.CodeBuildAction;
    };
    addTest(id: string, props: ShellableProps): {
        shellable: Shellable;
        action: cpipeline_actions.CodeBuildAction;
    };
    /**
     * Convenience/discovery method that defines a canary test in your account.
     * @param id the construct id
     * @param props canary options
     */
    addCanary(id: string, props: CanaryProps): Canary;
    addPublish(publisher: IPublisher, options?: AddPublishOptions): void;
    /**
     * Adds a change control policy to block transitions into the publish stage during certain time windows.
     * @param options the options to configure the change control policy.
     */
    addChangeControl(options?: AddChangeControlOptions): ChangeController;
    addSigning(signer: signing.ISigner, options?: signing.AddSigningOptions): void;
    signNuGetWithSigner(options: signing.SignNuGetWithSignerProps & signing.AddSigningOptions): void;
    publishToNpm(options: publishing.PublishToNpmProjectProps & AddPublishOptions): void;
    publishToMaven(options: publishing.PublishToMavenProjectProps & AddPublishOptions): void;
    publishToNuGet(options: publishing.PublishToNuGetProjectProps & AddPublishOptions): void;
    publishToGitHubPages(options: publishing.PublishDocsToGitHubProjectProps & AddPublishOptions): void;
    publishToGitHub(options: publishing.PublishToGitHubProps & AddPublishOptions): void;
    publishToPyPI(options: publishing.PublishToPyPiProps & AddPublishOptions): void;
    publishToS3(id: string, options: publishing.PublishToS3Props & AddPublishOptions): void;
    /**
     * Publish Golang code from `go` directory in build artifact to a GitHub repository.
     */
    publishToGolang(options: publishing.PublishToGolangProps): void;
    /**
     * Enables automatic bumps for the source repo.
     * @param options Options for auto bump (see AutoBumpOptions for description of defaults)
     */
    autoBump(options?: AutoBumpOptions): AutoBump;
    /**
     * Enables automatic merge backs for the source repo.
     * @param options Options for auto bump (see AutoMergeBackPipelineOptions for description of defaults)
     */
    autoMergeBack(options?: AutoMergeBackPipelineOptions): void;
    /**
     * Enables automatic builds of pull requests in the Github repository and posts the
     * results back as a comment with a public link to the build logs.
     */
    autoBuild(options?: AutoBuildOptions): AutoBuild;
    /**
     * The metric that tracks pipeline failures.
     */
    metricFailures(options: cloudwatch.MetricOptions): cloudwatch.Metric;
    /**
     * The metrics that track failure of each action within the pipeline.
     */
    metricActionFailures(options: cloudwatch.MetricOptions): cloudwatch.Metric[];
    addManualApprovalToStage(stageName: string, props?: cpipeline_actions.ManualApprovalActionProps): void;
    private addFailureAlarm;
    private addBuildFailureNotification;
    /**
     * @returns the stage or undefined if the stage doesn't exist
     */
    private getStage;
    private getOrCreateStage;
    private determineRunOrderForNewAction;
}
export interface IPublisher extends IConstruct {
    addToPipeline(stage: cpipeline.IStage, id: string, options: AddToPipelineOptions): void;
}
export interface AddToPipelineOptions {
    inputArtifact?: cpipeline.Artifact;
    runOrder?: number;
}
export interface AddChangeControlOptions {
    /**
     * The bucket in which the ChangeControl iCal document will be stored.
     *
     * @default a new bucket will be provisioned.
     */
    changeControlBucket?: s3.IBucket;
    /**
     * The key in which the iCal fille will be stored.
     *
     * @default 'change-control.ical'
     */
    changeControlObjectKey?: string;
    /**
     * Schedule to run the change controller on
     *
     * @default rate(15 minutes)
     */
    scheduleExpression?: string;
}
export interface AddPublishOptions {
    /**
     * The input artifact to use
     *
     * @default Signing output artifact when a signing stage is added to the
     * pipeline via `addSigning` or `signNuGetWithSigner`. Otherwise, the default
     * will be the build output artifact.
     */
    inputArtifact?: cpipeline.Artifact;
    /**
     * Stage name to add publishing job to
     *
     * By default, this will be the stage name `'Publish'`, but if you want to
     * separate out the publishing actions into different stages (in order to
     * block/unblock them separately for example) you can change this.
     *
     * Stages appear in the pipeline in the order they are referenced for
     * the first time.
     *
     * @default "Publish"
     */
    readonly stageName?: string;
}
export interface AddShellableOptions extends ShellableProps {
    /**
     * String to use as action name
     *
     * @default Id
     */
    actionName?: string;
    /**
     * Message to use as failure notification
     *
     * @default No notification
     */
    failureNotification?: string;
    /**
     * The input artifact to use
     *
     * @default Signing output artifact when a signing stage is added to the
     * pipeline via `addSigning` or `signNuGetWithSigner`. Otherwise, the default
     * will be the build output artifact.
     */
    inputArtifact?: cpipeline.Artifact;
}