feat(codepipeline-actions): support commands action

packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-commands.ts

@@ -0,0 +1,111 @@
+import * as codepipeline from 'aws-cdk-lib/aws-codepipeline';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as cdk from 'aws-cdk-lib';
+import { Duration } from 'aws-cdk-lib';
+import { IntegTest, ExpectedResult, Match } from '@aws-cdk/integ-tests-alpha';
+import * as cpactions from 'aws-cdk-lib/aws-codepipeline-actions';
+import { IKey, Key } from 'aws-cdk-lib/aws-kms';
+
+const app = new cdk.App();
+
+const stack = new cdk.Stack(app, 'aws-cdk-codepipeline-commands');
+
+const key: IKey = new Key(stack, 'EnvVarEncryptKey', {
+  description: 'sample key',
+});
+
+const bucket = new s3.Bucket(stack, 'PipelineBucket', {
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+  versioned: true,
+  encryptionKey: key,
+});
+const sourceOutput = new codepipeline.Artifact('SourceArtifact');
+const sourceAction = new cpactions.S3SourceAction({
+  actionName: 'Source',
+  output: sourceOutput,
+  bucket,
+  bucketKey: 'test.zip',
+});
+
+const commandsOutput = new codepipeline.Artifact('CommandsArtifact', ['my-dir/**/*']);
+const commandsAction = new cpactions.CommandsAction({
+  actionName: 'Commands',
+  commands: [
+    'pwd',
+    'ls -la',
+    'mkdir -p my-dir',
+    'echo "HelloWorld" > my-dir/file.txt',
+    'export MY_OUTPUT=my-key',
+    'touch ignored.txt',
+  ],
+  input: sourceOutput,
+  output: commandsOutput,
+  outputVariables: ['MY_OUTPUT', 'CODEBUILD_BUILD_ID', 'AWS_DEFAULT_REGION'],
+});
+
+const deployBucket = new s3.Bucket(stack, 'DeployBucket', {
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+});
+
+const pipeline = new codepipeline.Pipeline(stack, 'Pipeline', {
+  artifactBucket: bucket,
+  stages: [
+    {
+      stageName: 'Source',
+      actions: [sourceAction],
+    },
+    {
+      stageName: 'Compute',
+      actions: [commandsAction],
+    },
+    {
+      stageName: 'Deploy',
+      actions: [
+        new cpactions.S3DeployAction({
+          actionName: 'DeployAction',
+          extract: true,
+          input: commandsOutput,
+          bucket: deployBucket,
+          objectKey: commandsAction.variable('MY_OUTPUT'),
+          encryptionKey: key,
+        }),
+      ],
+    },
+  ],
+});
+
+const integ = new IntegTest(app, 'aws-cdk-codepipeline-commands-test', {
+  testCases: [stack],
+  diffAssets: true,
+});
+
+const putObjectCall = integ.assertions.awsApiCall('S3', 'putObject', {
+  Bucket: bucket.bucketName,
+  Key: 'test.zip',
+});
+
+const getObjectCall = integ.assertions.awsApiCall('S3', 'getObject', {
+  Bucket: deployBucket.bucketName,
+  Key: 'file.txt',
+});
+
+putObjectCall.next(
+  integ.assertions.awsApiCall('CodePipeline', 'getPipelineState', {
+    name: pipeline.pipelineName,
+  }).expect(ExpectedResult.objectLike({
+    stageStates: Match.arrayWith([
+      Match.objectLike({
+        stageName: 'Deploy',
+        latestExecution: Match.objectLike({
+          status: 'Succeeded',
+        }),
+      }),
+    ]),
+  })).waitForAssertions({
+    totalTimeout: Duration.minutes(5),
+  }).next(getObjectCall),
+);
+
+app.synth();

packages/aws-cdk-lib/aws-codepipeline-actions/lib/commands/commands-action.ts

@@ -0,0 +1,100 @@
+import { Construct } from 'constructs';
+import * as codepipeline from '../../../aws-codepipeline';
+import * as iam from '../../../aws-iam';
+import * as cdk from '../../../core';
+import { Action } from '../action';
+
+/**
+ * Construction properties of the `CommandsAction`.
+ */
+export interface CommandsActionProps extends codepipeline.CommonAwsActionProps {
+  /**
+   * The source to use as input for this action.
+   */
+  readonly input: codepipeline.Artifact;
+
+  /**
+   * The list of additional input Artifacts for this action.
+   *
+   * @default - no extra inputs
+   */
+  readonly extraInputs?: codepipeline.Artifact[];
+
+  /**
+   * The list of output Artifacts for this action.
+   *
+   * @default - the action will not have any outputs
+   */
+  readonly output?: codepipeline.Artifact;
+
+  /**
+   * The names of the variables in your environment that you want to export.
+   *
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+   * @default - No output variables are exported
+   */
+  readonly outputVariables?: string[];
+
+  /**
+   * Shell commands for the Commands action to run.
+   *
+   * All formats are supported except multi-line formats.
+   */
+  readonly commands: string[];
+}
+
+/**
+ * CodePipeline compute action that uses AWS Commands.
+ */
+export class CommandsAction extends Action {
+  constructor(props: CommandsActionProps) {
+    super({
+      ...props,
+      category: codepipeline.ActionCategory.COMPUTE,
+      provider: 'Commands',
+      artifactBounds: { minInputs: 1, maxInputs: 10, minOutputs: 0, maxOutputs: 1 },
+      inputs: [props.input, ...props.extraInputs || []],
+      outputs: props.output ? [props.output] : [],
+      commands: props.commands,
+      outputVariables: props.outputVariables,
+    });
+  }
+
+  /**
+   * Reference a CodePipeline variable exported in the Commands action.
+   *
+   * @param variableName the name of the variable to reference
+   * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+   */
+  public variable(variableName: string): string {
+    return this.variableExpression(variableName);
+  }
+
+  protected bound(scope: Construct, _stage: codepipeline.IStage, options: codepipeline.ActionBindOptions):
+  codepipeline.ActionConfig {
+    const logGroupArn = cdk.Stack.of(scope).formatArn({
+      service: 'logs',
+      resource: 'log-group',
+      resourceName: `/aws/codepipeline/${_stage.pipeline.pipelineName}:*`,
+      arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+    });
+
+    // grant the Pipeline role the required permissions to the log group
+    options.role.addToPrincipalPolicy(new iam.PolicyStatement({
+      resources: [logGroupArn],
+      actions: [
+        // To put the logs in the log group
+        // see: https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-Commands.html#action-reference-Commands-policy
+        'logs:CreateLogGroup',
+        'logs:CreateLogStream',
+        'logs:PutLogEvents',
+        // To view the logs in the Commands action on the CodePipeline console
+        // see: https://docs.aws.amazon.com/codepipeline/latest/userguide/security-iam-permissions-console-logs.html
+        'logs:GetLogEvents',
+      ],
+    }));
+
+    // `CommandsAction` does not need the `configuration` in the `ActionConfig`.
+    return {};
+  }
+}

packages/aws-cdk-lib/aws-codepipeline-actions/lib/index.ts

@@ -6,6 +6,7 @@ export * from './codebuild/build-action';
 export * from './codecommit/source-action';
 export * from './codedeploy/ecs-deploy-action';
 export * from './codedeploy/server-deploy-action';
+export * from './commands/commands-action';
 export * from './ecr/source-action';
 export * from './ecs/deploy-action';
 export * from './elastic-beanstalk/deploy-action';

packages/aws-cdk-lib/aws-codepipeline/lib/action.ts

@@ -13,6 +13,7 @@ export enum ActionCategory {
   APPROVAL = 'Approval',
   DEPLOY = 'Deploy',
   INVOKE = 'Invoke',
+  COMPUTE = 'Compute',
 }
 
 /**
@@ -104,6 +105,20 @@ export interface ActionProperties {
    * @default - a name will be generated, based on the stage and action names
    */
   readonly variablesNamespace?: string;
+
+  /**
+   * Shell commands for the Commands action to run.
+   *
+   * @default - no commands
+   */
+  readonly commands?: string[];
+
+  /**
+   * The names of the variables in your environment that you want to export.
+   *
+   * @default - no output variables
+   */
+  readonly outputVariables?: string[];
 }
 
 export interface ActionBindOptions {

packages/aws-cdk-lib/aws-codepipeline/lib/artifact.ts

@@ -11,24 +11,31 @@ export class Artifact {
    * Mainly meant to be used from `decdk`.
    *
    * @param name the (required) name of the Artifact
+   * @param files file paths that you want to export as output artifacts for the action. (can only be used in artifacts for `CommandAction`)
    */
-  public static artifact(name: string): Artifact {
-    return new Artifact(name);
+  public static artifact(name: string, files?: string[]): Artifact {
+    return new Artifact(name, files);
   }
 
   private _artifactName?: string;
+  private _artifactFiles?: string[];
   private readonly metadata: { [key: string]: any } = {};
 
-  constructor(artifactName?: string) {
+  constructor(artifactName?: string, artifactFiles?: string[]) {
     validation.validateArtifactName(artifactName);
 
     this._artifactName = artifactName;
+    this._artifactFiles = artifactFiles;
   }
 
   public get artifactName(): string | undefined {
     return this._artifactName;
   }
 
+  public get artifactFiles(): string[] | undefined {
+    return this._artifactFiles;
+  }
+
   /**
    * Returns an ArtifactPath for a file within this artifact.
    * CfnOutput is in the form "<artifact-name>::<file-name>"

packages/aws-cdk-lib/aws-codepipeline/lib/private/full-action-descriptor.ts

@@ -27,6 +27,8 @@ export class FullActionDescriptor {
   public readonly region?: string;
   public readonly role?: iam.IRole;
   public readonly configuration: any;
+  public readonly commands?: string[];
+  public readonly outputVariables?: string[];
 
   constructor(props: FullActionDescriptorProps) {
     this.action = props.action;
@@ -45,6 +47,8 @@ export class FullActionDescriptor {
     this.role = actionProperties.role ?? props.actionRole;
 
     this.configuration = props.actionConfig.configuration;
+    this.commands = actionProperties.commands;
+    this.outputVariables = actionProperties.outputVariables;
   }
 }
 

packages/aws-cdk-lib/aws-codepipeline/lib/private/stage.ts

@@ -173,17 +173,19 @@ export class Stage implements IStage {
         provider: action.provider,
       },
       configuration: action.configuration,
+      commands: action.commands,
+      outputVariables: action.outputVariables,
       runOrder: action.runOrder,
       roleArn: action.role ? action.role.roleArn : undefined,
       region: action.region,
       namespace: action.namespace,
     };
   }
 
-  private renderArtifacts(artifacts: Artifact[]): CfnPipeline.InputArtifactProperty[] {
+  private renderArtifacts(artifacts: Artifact[]): CfnPipeline.OutputArtifactProperty[] {
     return artifacts
       .filter(a => a.artifactName)
-      .map(a => ({ name: a.artifactName! }));
+      .map(a => ({ name: a.artifactName!, files: a.artifactFiles }));
   }
 }