aws-delivlib/lib/pull-request/pr.d.ts

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

import { aws_cloudwatch as cloudwatch, aws_codebuild as cbuild } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BuildEnvironmentProps } from '../build-env';
import { WritableGitHubRepo } from '../repo';
/**
 * Properties for creating a Pull Request Job.
 */
export interface AutoPullRequestOptions {
    /**
     * The base branch of the PR.
     *
     * @default 'master'
     */
    base?: Base;
    /**
     * True if you only want to push the head branch without creating a PR.
     * Useful when used along with 'commits' to execute a commit-and-push automatically.
     *
     * // TODO: Consider moving this functionality to a separate construct.
     *
     * @default false
     */
    readonly pushOnly?: boolean;
    /**
     * Title of the PR.
     *
     * @default `Merge ${head} to ${base}`
     */
    title?: string;
    /**
     * Body the PR. Note that the body is updated post PR creation,
     * this means you can use the $PR_NUMBER env variable to refer to the PR itself.
     *
     * @default - no body.
     */
    body?: string;
    /**
     * Labels applied to the PR.
     *
     * @default - no labels.
     */
    labels?: string[];
    /**
     * Build environment for the CodeBuild job.
     *
     * @default - default configuration.
     */
    build?: BuildEnvironmentProps;
    /**
     * Git clone depth.
     *
     * @default 0 (clones the entire repository revisions)
     */
    cloneDepth?: number;
    /**
     * Key value pairs of variables to export. These variables will be available for dynamic evaluation in any
     * subsequent command.
     *
     * Key - Variable name (e.g VERSION)
     * Value - Command that evaluates to the value of the variable (e.g 'git describe')
     *
     * Example:
     *
     * Configure an export in the form of:
     *
     * { 'VERSION': 'git describe' }
     *
     * Use the $VERSION variable in the PR title: 'chore(release): $VERSION'
     *
     * Note that these exports are executed after the `commands` execution,
     * so they have access to the artifacts said commands produce (e.g version bump).
     *
     * @default - no exports
     */
    exports?: {
        [key: string]: string;
    };
    /**
     * The schedule to produce an automatic PR.
     *
     * The expression can be one of:
     *
     *  - cron expression, such as "cron(0 12 * * ? *)" will trigger every day at 12pm UTC
     *  - rate expression, such as "rate(1 day)" will trigger every 24 hours from the time of deployment
     *
     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html
     *
     * @default - no schedule, should be triggered manually.
     */
    scheduleExpression?: string;
}
export interface AutoPullRequestProps extends AutoPullRequestOptions {
    /**
     * The repository to create a PR in.
     */
    repo: WritableGitHubRepo;
    /**
     * A set of commands to run against the head branch.
     * Useful for things like version bumps or any auto-generated commits.
     *
     * Note that you cannot use export keys in these commands (See `exports` property)
     *
     * @default - no commands.
     */
    commands?: string[];
    /**
     * The head branch of the PR.
     */
    head: Head;
    /**
     * The exit code of this command determines whether or not to proceed with the
     * PR creation. If configured, this command is the first one to run, and if it fails, all
     * other commands will be skipped.
     *
     * This command is the first to execute, and should not assume any pre-existing state.
     *
     * @default - no condition
     */
    condition?: string;
    /**
     * If any PR labeled with the given labels is still open, no new PR will be created
     *
     * @default - don't look at open PRs
     */
    readonly skipIfOpenPrsWithLabels?: string[];
    /**
     * Description string for the CodeBuild project
     *
     * @default - No description
     */
    readonly projectDescription?: string;
}
/**
 * Properties for configuring the base branch of the PR.
 */
export interface Base {
    /**
     * Branch name.
     *
     * This branch must exist.
     *
     * @default 'master'
     */
    readonly name?: string;
}
/**
 * Properties for configuring the head branch of the PR.
 */
export interface Head {
    /**
     * Branch name.
     *
     * This branch will be created if it doesn't exist.
     */
    readonly name: string;
    /**
     * The source sha of the branch.
     *
     * If the given branch already exists, this sha will be auto-merged onto it. Note that in such a case,
     * the PR creation might fail in case there are merge conflicts.
     *
     * If the given branch doesn't exist, the newly created branch will be based of this hash.
     *
     * Note that dynamic exports are not allowed for this property.
     *
     * @default - the base branch of the pr.
     */
    readonly source?: string;
}
/**
 * Creates a CodeBuild job that, when triggered, opens a GitHub Pull Request.
 */
export declare class AutoPullRequest extends Construct {
    /**
     * CloudWatch alarm that will be triggered if the job fails.
     */
    readonly alarm: cloudwatch.Alarm;
    /**
     * The CodeBuild project this construct creates.
     */
    readonly project: cbuild.IProject;
    private readonly props;
    private readonly baseBranch;
    private readonly headSource;
    private readonly exports;
    constructor(parent: Construct, id: string, props: AutoPullRequestProps);
    private createHead;
    private cloneIfNeeded;
    private runCommands;
    private configureSshAccess;
    private pushHead;
    private skipIfOpenPrs;
    private createPullRequest;
    private githubCurl;
    private githubCurlGet;
}