npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@flit/cdk-pipeline

v1.1.1

Published

A highly customizable and extensible CI/CD pipeline intended as alternative to CDK's native CodePipeline

Downloads

389

Readme

This library exposes a highly customizable and extensible L3 pipeline construct intended as an alternative to the CDK native L3 CodePipeline construct which has some inherent limitations in capability and extensibility.

The documentation provides the tools and documentation to get your own pipeline up and running and build your own custom segments.

Usage

Installation

The package is available on NPM and can be installed using your package manager of choice:

npm i @flit/cdk-pipeline
pnpm add @flit/cdk-pipeline
yarn add @flit/cdk-pipeline

Basics

The snippet bellow is a basic example of a pipeline which will run whenever a change is detected in a GitHub repository. The pipeline will update itself and, deploy and update a user defined stack. This example demonstrates the three basic elements that make up a pipeline:

- Pipeline

The Pipeline construct will create a CloudFormation Stack which contains the pipeline and all of the required peripheral resources to make it work.

- Segment

A Segment is simply a pre-configured set of pipeline actions which together represent a commonly used CI/CD pattern, like for example building and deploying a stack.

To build properly, a Pipeline requires at least one SourceSegment, exactly one PipelineSegment and at least one other segment.

- Artifact

An Artifact represents a pipeline artifact which can be used to pass information between stages. Every artifact needs to be the output of exactly one Segment and can be consumed by any segments that need that output.

import { App, SecretValue, Stack } from "aws-cdk-lib";
import {
  Pipeline,
  GitHubSourceSegment,
  PipelineSegment,
  StackSegment,
  Artifact,
} from "@flit/cdk-pipeline";

const APP = new App();

const SOURCE_ARTIFACT = new Artifact();
const BUILD_ARTIFACT = new Artifact();

new Pipeline(APP, "Pipeline", {
  rootDir: "./",
  segments: [
    new CodeStarSourceSegment({
      output: SOURCE_ARTIFACT,
      connectionArn: "code-star-connection-arn",
      owner: "owner-name",
      repository: "repo-name",
      branch: "branch-name",
    }),
    new PipelineSegment({
      input: SOURCE_ARTIFACT,
      output: BUILD_ARTIFACT,
      project: {
        environment: {
          computeType: ComputeType.MEDIUM,
          buildImage: LinuxBuildImage.AMAZON_LINUX_2_ARM_3,
          privileged: true,
        },
        buildSpec: BuildSpec.fromObject({
          version: "0.2",
          phases: {
            install: {
              "runtime-versions": {
                nodejs: "latest",
              },
              commands: ["npm i -g npm@latest", "npm ci"],
            },
            build: {
              commands: "cdk synth --strict --quiet",
            },
          },
        }),
      },
    }),
    new StackSegment({
      stack: new Stack(APP, "BackEnd"),
      input: BUILD_ARTIFACT,
    }),
  ],
});

The above code would produce a pipeline similar to this:

Multiple stacks

To add another stack to the pipeline you simply add another StackSegment with a new stack instance and the pipeline will handle the rest.

import { App, SecretValue, Stack } from "aws-cdk-lib";
import {
  Pipeline,
  GitHubSourceSegment,
  PipelineSegment,
  StackSegment,
  Artifact,
} from "@flit/cdk-pipeline";

const APP = new App();

const SOURCE_ARTIFACT = new Artifact();
const BUILD_ARTIFACT = new Artifact();

new Pipeline(APP, "Pipeline", {
  rootDir: "./",
  segments: [
    new CodeStarSourceSegment({
      output: SOURCE_ARTIFACT,
      connectionArn: "code-star-connection-arn",
      owner: "owner-name",
      repository: "repo-name",
      branch: "branch-name",
    }),
    new PipelineSegment({
      input: SOURCE_ARTIFACT,
      output: BUILD_ARTIFACT,
      project: {
        environment: {
          computeType: ComputeType.MEDIUM,
          buildImage: LinuxBuildImage.AMAZON_LINUX_2_ARM_3,
          privileged: true,
        },
        buildSpec: BuildSpec.fromObject({
          version: "0.2",
          phases: {
            install: {
              "runtime-versions": {
                nodejs: "latest",
              },
              commands: ["npm i -g npm@latest", "npm ci"],
            },
            build: {
              commands: "cdk synth --strict --quiet",
            },
          },
        }),
      },
    }),
    new StackSegment({
      stack: new Stack(APP, "BackEnd"),
      input: BUILD_ARTIFACT,
    }),
    new StackSegment({
      stack: new Stack(APP, "FrontEnd"),
      input: BUILD_ARTIFACT,
    }),
  ],
});

More complex example

In some cases you might have a build that bakes API endpoints generated by a previous stage into the stack assets during the build stage. Using the CDK native L3 CodePipeline construct makes this hard, but with this more flexible setup you can run another build for any stack that needs it, and use the previous stacks outputs in that build.

import { App, SecretValue, Stack } from "aws-cdk-lib";
import {
  Pipeline,
  GitHubSourceSegment,
  PipelineSegment,
  StackSegment,
  Artifact,
} from "@flit/cdk-pipeline";

const APP = new App();

const SOURCE_ARTIFACT = new Artifact();
const BUILD_ARTIFACT = new Artifact();
const FRONT_END_OUTPUT_ARTIFACT = new Artifact();

new Pipeline(APP, "Pipeline", {
  rootDir: "./",
  segments: [
    new CodeStarSourceSegment({
      output: SOURCE_ARTIFACT,
      connectionArn: "code-star-connection-arn",
      owner: "owner-name",
      repository: "repo-name",
      branch: "branch-name",
    }),
    new PipelineSegment({
      input: SOURCE_ARTIFACT,
      output: BUILD_ARTIFACT,
      project: {
        environment: {
          computeType: ComputeType.MEDIUM,
          buildImage: LinuxBuildImage.AMAZON_LINUX_2_ARM_3,
          privileged: true,
        },
        buildSpec: BuildSpec.fromObject({
          version: "0.2",
          phases: {
            install: {
              "runtime-versions": {
                nodejs: "latest",
              },
              commands: ["npm i -g npm@latest", "npm ci"],
            },
            build: {
              commands: "cdk synth --strict --quiet",
            },
          },
        }),
      },
    }),
    new StackSegment({
      stack: new Stack(APP, "BackEnd"),
      input: BUILD_ARTIFACT,
      output: FRONT_END_OUTPUT_ARTIFACT,
    }),
    new StackSegment({
      stack: new Stack(APP, "FrontEnd"),
      input: [SOURCE_ARTIFACT, FRONT_END_OUTPUT_ARTIFACT],
      project: {
        environment: {
          computeType: ComputeType.MEDIUM,
          buildImage: LinuxBuildImage.AMAZON_LINUX_2_ARM_3,
          privileged: true,
        },
        buildSpec: BuildSpec.fromObject({
          version: "0.2",
          phases: {
            install: {
              "runtime-versions": {
                nodejs: "latest",
              },
              commands: ["npm i -g npm@latest", "npm ci"],
            },
            build: {
              commands: [
                "do something with the STACK_1_OUTPUT_ARTIFACT",
                "cdk synth --strict --quiet",
              ],
            },
          },
        }),
      },
    }),
  ],
});

This example first build the project, deploys the Pipeline and BackEnd stacks and then rebuilds the project now with access to the outputs of the BackEnd stack. This allows you to now bake in any API endpoints dynamically generated in the BackEnd stack.

Building your own segment

The snippet bellow is a basic example showing a custom segment which simply adds a stage with two manual approval steps into the pipeline and allows you to optional give this step a name.

Each segment has two components consisting of two distinct classes:

- Segment

The main segment class is the class that will be used in your pipeline definition, and can be created by extending the Segment abstract class.

This class should not itself create any actual CDK constructs and is simply there to collect configuration trough the constructor. The constructor should take a single parameter called props which is a descendant of the SegmentProps interface.

The segment class also has to define the construct abstract function which returns an instance of a descendant of the SegmentConstructed abstract class.

- SegmentConstructed

This class will be returned by the construct function of your segment class and is itself a CDK construct. So in this class you can now allocate the CDK resources this segment requires as you are used to in any other CDK application.

You can pass any configuration information previously collected in the segment class trough the constructor.

import { IAction } from "aws-cdk-lib/aws-codepipeline";
import { ManualApprovalAction } from "aws-cdk-lib/aws-codepipeline-actions";

import { Segment, SegmentConstructed } from "./segment";
import { Pipeline } from "./pipeline";

export interface RequireApprovalSegmentProps {
  readonly name?: string;
}

/**
 * @category Segments
 */
export class DoubleApprovalSegment extends Segment {
  readonly props: RequireApprovalSegmentProps;

  constructor(props: RequireApprovalSegmentProps) {
    super({ ...props, input: undefined, output: undefined });
    this.props = props;
  }

  construct(scope: Pipeline): SegmentConstructed {
    return new RequireApprovalSegmentConstructed(
      scope,
      `RequireApproval`,
      this.props,
    );
  }
}

export interface RequireApprovalSegmentConstructedProps {
  readonly name?: string;
}

export class RequireApprovalSegmentConstructed extends SegmentConstructed {
  readonly name: string;
  readonly actions: IAction[];

  constructor(
    scope: Pipeline,
    id: string,
    props: RequireApprovalSegmentConstructedProps,
  ) {
    super(scope, id);

    this.name = props.name ?? id;

    this.actions = [
      new ManualApprovalAction({
        actionName: "ApproveChanges1",
        runOrder: 1,
      }),
      new ManualApprovalAction({
        actionName: "ApproveChanges2",
        runOrder: 2,
      }),
    ];
  }
}