Merge branch 'main' into project-option

packages/blueprints/blueprint-builder/static-assets/GETTING_STARTED.md

@@ -1,57 +1,82 @@
-# Blueprint development
+# Developing custom blueprints
 
-See blueprints github for full documentation and examples. https://github.com/aws/codecatalyst-blueprints/wiki
+You can develop a custom blueprint to deploy source repositories, workflows, environments, and other resources to CodeCatalyst projects.
 
-## Authoring a blueprint
+A blueprint takes user input options, combines the input options with the blueprint's logic to output a project bundle, which CodeCatalyst uses to
+make (or modify) resources for a project.
 
-The blueprint.ts file contains the blueprint code and options interface that will be used to generate the wizard. The blueprint can create source repositories, environments, and workflows based on options the user provides in the wizard.
+Blueprints can generate code in any language and create almost any CodeCatalyst resource. They often generate common files, configurations, and
+workflows for a project type. Blueprints can, for example, set up a web application project that contains a CDK stack and CodeCatalyst workflows that
+auto-deploys into an AWS account.
 
+You can modify the the Blueprint class and Options interface in `src/blueprint.ts` to customize your blueprint code and wizard options. For more
+information, see [Working with custom blueprints in CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/custom-blueprints.html).
 
-## Local development
+## Testing your blueprint locally
 
-This assumes you have already installed standard node tooling. If not see the section below on standard node tooling.
+Custom blueprints provide preview bundles as a result of a successful synthesis. The project bundle represents the source code, configuration, and
+resources deployed in a project. You can synthesize your blueprint to emulate project creation without having to create a project in CodeCatalyst. To
+synthesize your blueprint, use the following command:
 
 ```
-cd ./<my-blueprint-repository>
-nvm use
-yarn
-yarn projen
-yarn build
+yarn blueprint:synth
 ```
 
-Running a (re)synthesis. This will generate (or regenerate) your project from your blueprint locally. Running with `--cache` will first build a cache
-and then execute that, this takes slightly longer but emulates the wizard.
+The synthesis output is generated in the `synth/synth.[options-name]/proposed-bundle/` folder. For more information, see
+[Synthesis](https://docs.aws.amazon.com/codecatalyst/latest/userguide/custom-bp-concepts.html#synthesis-concept).
+
+If you're updating your custom blueprint, run the following command to resynthesize your blueprint:
 
 ```
-yarn blueprint:synth (--cache)
-yarn blueprint:resynth (--cache)
+yarn blueprint:resynth
 ```
 
-Publish your blueprint into codecatalyst in 'preview' mode. Previewed blueprints are only visible to your space.
+For more information, see [Resynthesis](https://docs.aws.amazon.com/codecatalyst/latest/userguide/custom-bp-concepts.html#resynthesis-concept).
+
+## Previewing and publishing a blueprint
+
+After configuring your custom blueprint locally, you can build and preview your blueprint before publishing it to your space.
+
+#### To view and publish a preview custom blueprint version
+
+Manually publish a preview version of your blueprint to your space using commands from your package.json file.
+
+1. Install necessary dependencies using the following command:
 
 ```
-yarn blueprint:preview
+yarn install
 ```
 
-## Installing standard Node tooling
+2. (Optional) Projen is an open-source tool that custom blueprints use to keep themselves updated and consistent. Blueprints come as Projen packages
+   because this framework provides you with the ability to build, bundle, and publish projects, and you can use the interface to manage a project's
+   configurations and settings. If you made changes to the `.projenrc.ts` file, regenerate the configuration of your project before building and
+   previewing your blueprint. Use the following command:
 
-This blueprint is a typescript project. You'll need to install standard node tooling globally.
+```
+yarn projen
+```
+
+3. Rebuild and preview your custom blueprint using the following command:
 
 ```
-#install nvm https://nvm.sh
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
-nvm use
-npm install npm@6.14.13 typescript@4.8.2 yarn ts-node webpack webpack-cli -g
-brew install jq
+yarn blueprint:preview
 ```
 
-You will also need access to the blueprint builder in your codecatalyst space. We recommend you develop on mac or a cloud desktop running linux. This
-guide assumes you are using a mac and are using `yarn`.
+To preview your custom blueprint in CodeCatalyst, navigate to the `See this blueprint at:` link provided in the preview command output. Check that the
+wizard UI, including text, appears as you expected based on your configuration. If you want to make further changes to your custom blueprint, you can
+edit the blueprint code, resynthesize the blueprint, and then run the preview command again.
 
-## Projen
+## Adding a blueprint to a space’s blueprint catalog
+
+Publish a release version of your blueprint using the following command:
+
+```
+yarn blueprint:release
+```
 
-Blueprints are projen projects. This allows the blueprints team to propgate lifecycle improvements and it allows users to resynthesize aspects of a
-project as they evolve. You'll have to make updates to the `projenrc.ts` as your project evolves. See Projen for further details.
-https://github.com/projen/projen
+To add the blueprint to your space catalog, navigate to the `Enable version version at:` link in the release command output. For more information, see
+[Adding a custom blueprint to a space catalog](https://docs.aws.amazon.com/codecatalyst/latest/userguide/add-remove-bp.html).
 
-The projenrc.ts represents the model of your codebase. As you update this file you should run `yarn projen` to regenerate this codebase.
+After developing and previewing your custom blueprint, you can publish and add your blueprint to the space’s blueprints catalog. For more information,
+see [Viewing a custom blueprint](https://docs.aws.amazon.com/codecatalyst/latest/userguide/view-bp.html), and
+[Adding a custom blueprint to a space](https://docs.aws.amazon.com/codecatalyst/latest/userguide/add-remove-bp.html).

packages/components/workflows/src/actions/action-build.ts

@@ -20,6 +20,7 @@ interface Step {
 
 export interface BuildActionConfiguration {
   Steps?: Step[];
+  Container?: BuildContainer;
 }
 
 /**
@@ -79,6 +80,12 @@ export interface BuildActionParameters {
   actionName: string;
   environment?: WorkflowEnvironment;
   dependsOn?: string[];
+  container?: BuildContainer;
+}
+
+export interface BuildContainer {
+  Registry: 'DockerHub' | 'ECR' | 'Other';
+  Image: string;
 }
 
 export const addGenericBuildAction = (
@@ -87,7 +94,7 @@ export const addGenericBuildAction = (
     workflow: WorkflowDefinition;
   },
 ): string => {
-  const { blueprint, workflow, steps, input, output } = params;
+  const { blueprint, workflow, steps, input, output, container } = params;
 
   const buildAction: ActionDefiniton = {
     Identifier: getDefaultActionIdentifier(ActionIdentifierAlias.build, blueprint.context.environmentId),
@@ -99,6 +106,7 @@ export const addGenericBuildAction = (
           Run: step,
         };
       }),
+      Container: container,
     },
   };
   if (params.environment) {

packages/components/workflows/src/workflow/workflow-builder.ts

@@ -36,83 +36,97 @@ export class WorkflowBuilder {
     this.definition = definition;
   }
 
-  addTrigger(trigger: TriggerDefiniton) {
+  addTrigger(trigger: TriggerDefiniton): WorkflowBuilder {
     this.definition.Triggers = this.definition.Triggers || [];
     this.definition.Triggers.push(trigger);
+    return this;
   }
 
-  addCompute(compute: ComputeDefintion) {
+  addCompute(compute: ComputeDefintion): WorkflowBuilder {
     this.definition.Compute = this.definition.Compute || compute;
+    return this;
   }
 
-  addBranchTrigger(branches = ['main'], filesChanged?: string[]) {
+  addBranchTrigger(branches = ['main'], filesChanged?: string[]): WorkflowBuilder {
     addGenericBranchTrigger(this.definition, branches, filesChanged);
+    return this;
   }
 
-  addPullRequestTrigger(events: PullRequestEvent[], branches = ['main'], filesChanged?: string[]) {
+  addPullRequestTrigger(events: PullRequestEvent[], branches = ['main'], filesChanged?: string[]): WorkflowBuilder {
     addGenericPullRequestTrigger(this.definition, events, branches, filesChanged);
+    return this;
   }
 
-  addBuildAction(configuration: BuildActionParameters) {
+  addBuildAction(configuration: BuildActionParameters): WorkflowBuilder {
     addGenericBuildAction({
       ...configuration,
       blueprint: this.blueprint,
       workflow: this.definition,
     });
+    return this;
   }
 
-  addCfnDeployAction(configuration: CfnDeployActionParameters) {
+  addCfnDeployAction(configuration: CfnDeployActionParameters): WorkflowBuilder {
     addGenericCloudFormationDeployAction({
       ...configuration,
       blueprint: this.blueprint,
       workflow: this.definition,
     });
+    return this;
   }
 
-  addCfnCleanupAction(configuration: CfnCleanupActionParameters) {
+  addCfnCleanupAction(configuration: CfnCleanupActionParameters): WorkflowBuilder {
     addGenericCloudFormationCleanupAction({
       ...configuration,
       blueprint: this.blueprint,
       workflow: this.definition,
     });
+    return this;
   }
 
-  addCdkDeployAction(configuration: CdkDeployActionParameters) {
+  addCdkDeployAction(configuration: CdkDeployActionParameters): WorkflowBuilder {
     addGenericCdkDeployAction({
       ...configuration,
       blueprint: this.blueprint,
       workflow: this.definition,
     });
+    return this;
   }
 
-  addCdkBootstrapAction(configuration: CdkBootstrapActionParameters) {
+  addCdkBootstrapAction(configuration: CdkBootstrapActionParameters): WorkflowBuilder {
     addGenericCdkBootstrapAction({
       ...configuration,
       blueprint: this.blueprint,
       workflow: this.definition,
     });
+    return this;
   }
 
-  addTestAction(configuration: TestReportActionParameters) {
+  addTestAction(configuration: TestReportActionParameters): WorkflowBuilder {
     addGenericTestReports({
       ...configuration,
       blueprint: this.blueprint,
       workflow: this.definition,
     });
+    return this;
   }
 
-  addPublishBlueprintAction(configuration: PublishBlueprintActionParameters) {
+  addPublishBlueprintAction(configuration: PublishBlueprintActionParameters): WorkflowBuilder {
     addGenericPublishBlueprintAction({
       ...configuration,
       blueprint: this.blueprint,
       workflow: this.definition,
     });
+    return this;
   }
 
-  addGenericAction<T extends {
-    ActionName: string;
-  }>(configuration: T & any) {
+  addGenericAction<
+    T extends {
+      ActionName: string;
+    },
+  >(configuration: T & any): WorkflowBuilder {
     this.definition.Actions = this.definition.Actions || {};
     this.definition.Actions[configuration.actionName] = configuration;
+    return this;
   }
 }