Skip to content

Latest commit

 

History

History
948 lines (584 loc) · 35.6 KB

API.md

File metadata and controls

948 lines (584 loc) · 35.6 KB

API Reference

Constructs

MasonGitHubWorkflow

CDK Pipelines for GitHub workflows.

Initializers 

import { MasonGitHubWorkflow } from '@magicbell/mason'

new MasonGitHubWorkflow(scope: Construct, id: string, props: MasonGitHubWorkflowProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props MasonGitHubWorkflowProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
addStage Deploy a single Stage by itself.
addWave Add a Wave to the pipeline, for deploying multiple Stages in parallel.
buildPipeline Send the current pipeline definition to the engine, and construct the pipeline.
addStageWithGitHubOptions Deploy a single Stage by itself with options for further GitHub configuration.
stepsToConfigureAws No description.
toString 
public toString(): string

Returns a string representation of this construct.

addStage 
public addStage(stage: Stage, options?: AddStageOpts): StageDeployment

Deploy a single Stage by itself.

Add a Stage to the pipeline, to be deployed in sequence with other Stages added to the pipeline. All Stacks in the stage will be deployed in an order automatically determined by their relative dependencies.

stageRequired
  • Type: aws-cdk-lib.Stage
optionsOptional
  • Type: aws-cdk-lib.pipelines.AddStageOpts
addWave 
public addWave(id: string, options?: WaveOptions): Wave

Add a Wave to the pipeline, for deploying multiple Stages in parallel.

Use the return object of this method to deploy multiple stages in parallel.

Example:

declare const pipeline: pipelines.CodePipeline;

const wave = pipeline.addWave('MyWave');
wave.addStage(new MyApplicationStage(this, 'Stage1'));
wave.addStage(new MyApplicationStage(this, 'Stage2'));
idRequired
  • Type: string
optionsOptional
  • Type: aws-cdk-lib.pipelines.WaveOptions
buildPipeline 
public buildPipeline(): void

Send the current pipeline definition to the engine, and construct the pipeline.

It is not possible to modify the pipeline after calling this method.

addStageWithGitHubOptions 
public addStageWithGitHubOptions(stage: Stage, options?: MasonAddGitHubStageOptions): StageDeployment

Deploy a single Stage by itself with options for further GitHub configuration.

Add a Stage to the pipeline, to be deployed in sequence with other Stages added to the pipeline. All Stacks in the stage will be deployed in an order automatically determined by their relative dependencies.

stageRequired
  • Type: aws-cdk-lib.Stage
optionsOptional
stepsToConfigureAws 
public stepsToConfigureAws(region: string, assumeRoleArn?: string): JobStep[]
regionRequired
  • Type: string
assumeRoleArnOptional
  • Type: string

Static Functions

Name Description
isConstruct Checks if x is a construct.
isPipeline Return whether the given object extends PipelineBase.
isConstruct 
import { MasonGitHubWorkflow } from '@magicbell/mason'

MasonGitHubWorkflow.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isPipeline 
import { MasonGitHubWorkflow } from '@magicbell/mason'

MasonGitHubWorkflow.isPipeline(x: any)

Return whether the given object extends PipelineBase.

We do attribute detection since we can't reliably use 'instanceof'.

xRequired
  • Type: any

Properties

Name Type Description
node constructs.Node The tree node.
cloudAssemblyFileSet aws-cdk-lib.pipelines.FileSet The FileSet tha contains the cloud assembly.
synth aws-cdk-lib.pipelines.IFileSetProducer The build step that produces the CDK Cloud Assembly.
waves aws-cdk-lib.pipelines.Wave[] The waves in this pipeline.
awsCredentials cdk-pipelines-github.AwsCredentialsProvider No description.
publishAssetsAuthRegion string No description.
workflowFile cdk-pipelines-github.YamlFile No description.
workflowName string No description.
workflowPath string No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

cloudAssemblyFileSetRequired 
public readonly cloudAssemblyFileSet: FileSet;
  • Type: aws-cdk-lib.pipelines.FileSet

The FileSet tha contains the cloud assembly.

This is the primary output of the synth step.

synthRequired 
public readonly synth: IFileSetProducer;
  • Type: aws-cdk-lib.pipelines.IFileSetProducer

The build step that produces the CDK Cloud Assembly.

wavesRequired 
public readonly waves: Wave[];
  • Type: aws-cdk-lib.pipelines.Wave[]

The waves in this pipeline.

awsCredentialsRequired 
public readonly awsCredentials: AwsCredentialsProvider;
  • Type: cdk-pipelines-github.AwsCredentialsProvider
publishAssetsAuthRegionRequired 
public readonly publishAssetsAuthRegion: string;
  • Type: string
workflowFileRequired 
public readonly workflowFile: YamlFile;
  • Type: cdk-pipelines-github.YamlFile
workflowNameRequired 
public readonly workflowName: string;
  • Type: string
workflowPathRequired 
public readonly workflowPath: string;
  • Type: string

Structs

ExtendedJobSettings

Initializer 

import { ExtendedJobSettings } from '@magicbell/mason'

const extendedJobSettings: ExtendedJobSettings = { ... }

Properties

Name Type Description
if string jobs.<job_id>.if.
timeoutMinutes number Timeout in minutes after which this job will be canceled if it hasn't finished.
ifOptional 
public readonly if: string;
  • Type: string

jobs.<job_id>.if.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif

timeoutMinutesOptional 
public readonly timeoutMinutes: number;
  • Type: number

Timeout in minutes after which this job will be canceled if it hasn't finished.

MasonAddGitHubStageOptions

Initializer 

import { MasonAddGitHubStageOptions } from '@magicbell/mason'

const masonAddGitHubStageOptions: MasonAddGitHubStageOptions = { ... }

Properties

Name Type Description
post aws-cdk-lib.pipelines.Step[] Additional steps to run after all of the stacks in the stage.
pre aws-cdk-lib.pipelines.Step[] Additional steps to run before any of the stacks in the stage.
stackSteps aws-cdk-lib.pipelines.StackSteps[] Instructions for stack level steps.
gitHubEnvironment cdk-pipelines-github.GitHubEnvironment Run the stage in a specific GitHub Environment.
jobSettings cdk-pipelines-github.JobSettings Job level settings that will be applied to all jobs in the stage.
stackCapabilities cdk-pipelines-github.StackCapabilities[] In some cases, you must explicitly acknowledge that your CloudFormation stack template contains certain capabilities in order for CloudFormation to create the stack.
extendedJobSettings ExtendedJobSettings Additional job level settings that will be applied to all jobs in the workflow, including synth and asset deploy jobs.
postOptional 
public readonly post: Step[];
  • Type: aws-cdk-lib.pipelines.Step[]
  • Default: No additional steps

Additional steps to run after all of the stacks in the stage.

preOptional 
public readonly pre: Step[];
  • Type: aws-cdk-lib.pipelines.Step[]
  • Default: No additional steps

Additional steps to run before any of the stacks in the stage.

stackStepsOptional 
public readonly stackSteps: StackSteps[];
  • Type: aws-cdk-lib.pipelines.StackSteps[]
  • Default: No additional instructions

Instructions for stack level steps.

gitHubEnvironmentOptional 
public readonly gitHubEnvironment: GitHubEnvironment;
  • Type: cdk-pipelines-github.GitHubEnvironment
  • Default: no GitHub environment

Run the stage in a specific GitHub Environment.

If specified, any protection rules configured for the environment must pass before the job is set to a runner. For example, if the environment has a manual approval rule configured, then the workflow will wait for the approval before sending the job to the runner.

Running a workflow that references an environment that does not exist will create an environment with the referenced name.

https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment

jobSettingsOptional 
public readonly jobSettings: JobSettings;
  • Type: cdk-pipelines-github.JobSettings

Job level settings that will be applied to all jobs in the stage.

Currently the only valid setting is 'if'.

stackCapabilitiesOptional 
public readonly stackCapabilities: StackCapabilities[];
  • Type: cdk-pipelines-github.StackCapabilities[]
  • Default: ['CAPABILITY_IAM']

In some cases, you must explicitly acknowledge that your CloudFormation stack template contains certain capabilities in order for CloudFormation to create the stack.

If insufficiently specified, CloudFormation returns an InsufficientCapabilities error.

extendedJobSettingsOptional 
public readonly extendedJobSettings: ExtendedJobSettings;

Additional job level settings that will be applied to all jobs in the workflow, including synth and asset deploy jobs.

Currently, the only valid setting is 'timeoutMinutes'. You can use this to run jobs only in specific repositories.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-only-run-job-for-specific-repository

MasonGitHubWorkflowProps

Initializer 

import { MasonGitHubWorkflowProps } from '@magicbell/mason'

const masonGitHubWorkflowProps: MasonGitHubWorkflowProps = { ... }

Properties

Name Type Description
synth aws-cdk-lib.pipelines.IFileSetProducer The build step that produces the CDK Cloud Assembly.
awsCredentials cdk-pipelines-github.AwsCredentialsSecrets Names of GitHub repository secrets that include AWS credentials for deployment.
awsCreds cdk-pipelines-github.AwsCredentialsProvider Configure provider for AWS credentials used for deployment.
buildContainer cdk-pipelines-github.ContainerOptions Build container options.
cdkCliVersion string Version of the CDK CLI to use.
concurrency cdk-pipelines-github.ConcurrencyOptions GitHub workflow concurrency.
dockerAssetJobSettings cdk-pipelines-github.DockerAssetJobSettings Job level settings applied to all docker asset publishing jobs in the workflow.
dockerCredentials cdk-pipelines-github.DockerCredential[] The Docker Credentials to use to login.
gitHubActionRoleArn string A role that utilizes the GitHub OIDC Identity Provider in your AWS account.
jobSettings cdk-pipelines-github.JobSettings Job level settings that will be applied to all jobs in the workflow, including synth and asset deploy jobs.
postBuildSteps cdk-pipelines-github.JobStep[] GitHub workflow steps to execute after build.
preBuildSteps cdk-pipelines-github.JobStep[] GitHub workflow steps to execute before build.
preSynthed boolean Indicates if the repository already contains a synthesized cdk.out directory, in which case we will simply checkout the repo in jobs that require cdk.out.
publishAssetsAuthRegion string Will assume the GitHubActionRole in this region when publishing assets.
runner cdk-pipelines-github.Runner The type of runner to run the job on.
workflowName string Name of the workflow.
workflowPath string File path for the GitHub workflow.
workflowTriggers cdk-pipelines-github.WorkflowTriggers GitHub workflow triggers.
extendedJobSettings ExtendedJobSettings Additional job level settings that will be applied to all jobs in the workflow, including synth and asset deploy jobs.
namer IMasonNamer Optional object that can name jobs and stacks.
synthRequired 
public readonly synth: IFileSetProducer;
  • Type: aws-cdk-lib.pipelines.IFileSetProducer

The build step that produces the CDK Cloud Assembly.

The primary output of this step needs to be the cdk.out directory generated by the cdk synth command.

If you use a ShellStep here and you don't configure an output directory, the output directory will automatically be assumed to be cdk.out.

awsCredentialsOptional
  • Deprecated: Use awsCreds.fromGitHubSecrets() instead.
public readonly awsCredentials: AwsCredentialsSecrets;
  • Type: cdk-pipelines-github.AwsCredentialsSecrets
  • Default: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Names of GitHub repository secrets that include AWS credentials for deployment.

awsCredsOptional 
public readonly awsCreds: AwsCredentialsProvider;
  • Type: cdk-pipelines-github.AwsCredentialsProvider
  • Default: Get AWS credentials from GitHub secrets AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Configure provider for AWS credentials used for deployment.

buildContainerOptional 
public readonly buildContainer: ContainerOptions;
  • Type: cdk-pipelines-github.ContainerOptions
  • Default: GitHub defaults

Build container options.

cdkCliVersionOptional 
public readonly cdkCliVersion: string;
  • Type: string
  • Default: automatic

Version of the CDK CLI to use.

concurrencyOptional 
public readonly concurrency: ConcurrencyOptions;
  • Type: cdk-pipelines-github.ConcurrencyOptions
  • Default: no concurrency settings

GitHub workflow concurrency.

dockerAssetJobSettingsOptional 
public readonly dockerAssetJobSettings: DockerAssetJobSettings;
  • Type: cdk-pipelines-github.DockerAssetJobSettings
  • Default: no additional settings

Job level settings applied to all docker asset publishing jobs in the workflow.

dockerCredentialsOptional 
public readonly dockerCredentials: DockerCredential[];
  • Type: cdk-pipelines-github.DockerCredential[]

The Docker Credentials to use to login.

If you set this variable, you will be logged in to docker when you upload Docker Assets.

gitHubActionRoleArnOptional
  • Deprecated: Use awsCreds.fromOpenIdConnect() instead.
public readonly gitHubActionRoleArn: string;
  • Type: string
  • Default: GitHub repository secrets are used instead of OpenId Connect role.

A role that utilizes the GitHub OIDC Identity Provider in your AWS account.

If supplied, this will be used instead of awsCredentials.

You can create your own role in the console with the necessary trust policy to allow gitHub actions from your gitHub repository to assume the role, or you can utilize the GitHubActionRole construct to create a role for you.

jobSettingsOptional 
public readonly jobSettings: JobSettings;
  • Type: cdk-pipelines-github.JobSettings

Job level settings that will be applied to all jobs in the workflow, including synth and asset deploy jobs.

Currently the only valid setting is 'if'. You can use this to run jobs only in specific repositories.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-only-run-job-for-specific-repository

postBuildStepsOptional 
public readonly postBuildSteps: JobStep[];
  • Type: cdk-pipelines-github.JobStep[]
  • Default: []

GitHub workflow steps to execute after build.

preBuildStepsOptional 
public readonly preBuildSteps: JobStep[];
  • Type: cdk-pipelines-github.JobStep[]
  • Default: []

GitHub workflow steps to execute before build.

preSynthedOptional 
public readonly preSynthed: boolean;
  • Type: boolean
  • Default: false

Indicates if the repository already contains a synthesized cdk.out directory, in which case we will simply checkout the repo in jobs that require cdk.out.

publishAssetsAuthRegionOptional 
public readonly publishAssetsAuthRegion: string;
  • Type: string
  • Default: "us-west-2"

Will assume the GitHubActionRole in this region when publishing assets.

This is NOT the region in which the assets are published.

In most cases, you do not have to worry about this property, and can safely ignore it.

runnerOptional 
public readonly runner: Runner;
  • Type: cdk-pipelines-github.Runner
  • Default: Runner.UBUNTU_LATEST

The type of runner to run the job on.

The runner can be either a GitHub-hosted runner or a self-hosted runner.

workflowNameOptional 
public readonly workflowName: string;
  • Type: string
  • Default: "deploy"

Name of the workflow.

workflowPathOptional 
public readonly workflowPath: string;
  • Type: string
  • Default: ".github/workflows/deploy.yml"

File path for the GitHub workflow.

workflowTriggersOptional 
public readonly workflowTriggers: WorkflowTriggers;
  • Type: cdk-pipelines-github.WorkflowTriggers
  • Default: By default, workflow is triggered on push to the main branch and can also be triggered manually (workflow_dispatch).

GitHub workflow triggers.

extendedJobSettingsOptional 
public readonly extendedJobSettings: ExtendedJobSettings;

Additional job level settings that will be applied to all jobs in the workflow, including synth and asset deploy jobs.

Currently, the only valid setting is 'timeoutMinutes'. You can use this to run jobs only in specific repositories.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-only-run-job-for-specific-repository

namerOptional 
public readonly namer: IMasonNamer;

Optional object that can name jobs and stacks.

This can be useful to avoid name conflicts.

Protocols

IMasonNamer

Methods

Name Description
gitHubActionJobName Use this function to override GitHub Actions job names.
stackDisplayName Use this function to set the display name of stack deployment jobs.
stackName Use this function to override deployed stack names.
gitHubActionJobName 
public gitHubActionJobName(originalName: string, step: Step): string

Use this function to override GitHub Actions job names.

This is useful when the job name is dynamic but the pipeline code should remain static.

originalNameRequired
  • Type: string
stepRequired
  • Type: aws-cdk-lib.pipelines.Step
stackDisplayName 
public stackDisplayName(originalName: string, stack: StackDeployment): string

Use this function to set the display name of stack deployment jobs.

By default, the name of the job will be the name of the stack. Sometimes we may want the name to be different. For example, if the stack name is dynamic but the pipeline code should remain static.

This will be used for stack delpoyment job names and its display name.

originalNameRequired
  • Type: string
stackRequired
  • Type: aws-cdk-lib.pipelines.StackDeployment
stackName 
public stackName(originalName: string, stack: StackDeployment): string

Use this function to override deployed stack names.

This is useful when the stack name is dynamic but the pipeline code should remain static.

originalNameRequired
  • Type: string
stackRequired
  • Type: aws-cdk-lib.pipelines.StackDeployment