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

opinionated-ci-pipeline

v4.2.0

Published

CI/CD on AWS with feature-branch builds, developer-environment deployments, and build status notifications.

Downloads

2,145

Readme

Opinionated CDK CI Pipeline

NPM PyPI

CI/CD utilizing CDK Pipelines.

Features:

  • pipeline deploying application from the default branch to multiple environments on multiple accounts,
  • feature branch deployments to ephemeral environments,
  • development environments deployments from the local CLI,
  • build status notifications to repository commits,
  • build failures notifications to SNS,
  • supports commit message tags to skip deployments ([skip ci] or [no ci]).

Currently supported source repositories are GitHub and Bitbucket.

Pipeline architecture:

Pipeline architecture

See the announcement blog post for more details and examples.

Table of contents

Usage

To set up, you need to complete the following steps:

  1. Install the library in your project.
  2. Specify context parameters.
  3. Create CDKApplication with build process configuration.
  4. Create repository access token.
  5. Bootstrap the CDK on the AWS account(s).
  6. Deploy the CI.

At the end, you will have CI pipeline in place, and be able to deploy your own custom environment from the CLI as well.

1. Install

For Node.js:

npm install -D opinionated-ci-pipeline

For Python:

pip install opinionated-ci-pipeline

2. Set context parameters

Add project name and environments config in the cdk.json as context parameters. Each environment must have account and region provided.

{
  "app": "...",
  "context": {
    "projectName": "myproject",
    "environments": {
      "default": {
        "account": "111111111111",
        "region": "us-east-1"
      },
      "prod": {
        "account": "222222222222",
        "region": "us-east-1"
      }
    }
  }
}

The project name will be used as a prefix for the deployed CI Stack name.

Environment names should match environments provided later in the CDKApplication configuration.

The optional default environment configuration is used as a fallback.

The CI pipeline itself is deployed to the ci environment, with a fallback to the default environment as well.

3. Create CDKApplication

In the CDK entrypoint script referenced by the cdk.json app field, replace the content with an instance of CDKApplication:

#!/usr/bin/env node
import 'source-map-support/register';
import {ExampleStack} from '../lib/exampleStack';
import {CDKApplication} from 'opinionated-ci-pipeline';

new CDKApplication({
    stacks: {
        create: (scope, projectName, envName) => {
            new ExampleStack(scope, 'ExampleStack', {stackName: `${projectName}-${envName}-ExampleStack`});
        },
    },
    repository: {
        host: 'github',
        name: 'organization/repository',
    },
    packageManager: 'npm',
    pipeline: [
        {
            environment: 'test',
            post: [
                'echo "do integration tests here"',
            ],
        },
        {
            environment: 'prod',
        },
    ],
});

This configures the application with one Stack and a pipeline deploying to an environment test, running integration tests, and deploying to environment prod.

The test and prod environments will be deployed from the branch main (by default). All other branches will be deployed to separate environments. Those feature-branch environments will be destroyed after the branch is removed.

To allow deployment of multiple environments, the Stack(s) name must include the environment name.

4. Create repository access token

An access to the source repository is required to fetch code and send build status notifications.

Once access token is created, save it in SSM Parameter Store as a SecureString under the path /{projectName}/ci/repositoryAccessToken.

See instructions below on how to create the token for each supported repository host.

GitHub

Create a fine-grained personal access token with read-only access for Contents read and write access for Commit statuses and Webhooks.

Bitbucket

In Bitbucket, go to your repository. Open Settings → Access tokens. There, create a new Repository Access Token with repository:write and webhook scopes.

5. Bootstrap the CDK

Bootstrap the CDK on the account holding the CI pipeline and all other accounts the pipeline will be deploying to.

When bootstrapping other accounts, add the --trust parameter with the account ID of the account holding the pipeline.

6. Deploy the CI Stack

Run:

cdk deploy -c ci=true

Deploy development environment

Run:

cdk deploy -c env=MYENV --all

to deploy arbitrary environments.

Parameters

If provided, the install command will be set to install dependencies using given package manager.

Commands executed to build and deploy the application. The following commands are set by default:

  • install
  • synthPipeline
  • deployEnvironment
  • destroyEnvironment

If you override the install command, either install the aws-cdk@2 globally or modify the other 3 commands to use the local cdk binary. Commands executed on particular builds:

  • main pipeline:
    • preInstall
    • install
    • buildAndTest
    • synthPipeline
  • feature branch environment deployment:
    • preInstall
    • install
    • buildAndTest
    • preDeployEnvironment
    • deployEnvironment
    • postDeployEnvironment
  • feature branch environment destruction:
    • preInstall
    • install
    • preDestroyEnvironment
    • destroyEnvironment
    • postDestroyEnvironment

The location where CDK outputs synthetized files. Corresponds to the CDK Pipelines ShellStepProps#primaryOutputDirectory.

Whether to remove the CI resources from the beginning of the aws:cdk:path metadata when deploying from the main pipeline.

Notifications and alarms

Stack creates SNS Topics with notifications for main pipeline failures and feature branch build failures. Their ARNs are saved in SSM Parameters and outputed by the stack:

  • main pipeline failures:
    • SSM: /{projectName}/ci/pipelineFailuresTopicArn
    • Stack exported output: {projectName}-ci-pipelineFailuresTopicArn
  • feature branch build failures:
    • SSM: /{projectName}/ci/featureBranchBuildFailuresTopicArn
    • Stack exported output: {projectName}-ci-featureBranchBuildFailuresTopicArn

If you setup Slack notifications, you can configure those failure notifications to be sent to Slack.

Moreover, if you setup Slack notifications, an additional SNS Topic will be created to which you can send CloudWatch Alarms. It's ARN is provided:

  • SSM: /{projectName}/ci/slackAlarmsTopicArn
  • Stack exported output: {projectName}-ci-slackAlarmsTopicArn

How to

Run unit tests during build

Set commands in the commands.buildAndTest:

{
    commands: {
        buildAndTest: [
            'npm run lint',
            'npm run test',
        ]
    }
}

Enable Docker

Set codeBuild.buildEnvironment.privileged to true:

{
    codeBuild: {
        buildEnvironment: {
            privileged: true
        }
    }
}

Library development

Project uses jsii to generate packages for different languages.

Install dependencies:

npm install

Build:

npm run build

Change example/bin/cdk.ts repository to point to your repository.

Then, install and deploy the CI for the example application:

cd example
pnpm install
pnpm cdk deploy -c ci=true

One-line command to re-deploy after changes (run from the example directory):

(cd .. && npm run build && cd example && cdk deploy -m direct -c ci=true)