aws-delivlib

aws-delivlib

aws-delivlib is a fabulous library for defining continuous pipelines for building, testing and publishing code libraries through AWS CodeBuild and AWS CodePipeline.

This guide will walk you through setting up a delivlib pipeline and utilizing all it's features.

A delivlib pipeline consists of the following sequential stages. Each stage will execute all tasks concurrently:

1. Source
   • CodeCommit
   • GitHub
2. Build
3. Tests
4. Publish
   • npm.js
   • NuGet
   • Maven Central
   • GitHub Releases
   • GitHub Pages

Installation

To install, use npm / yarn:

$ npm i aws-delivlib

or:

$ yarn add aws-delivlib

and import the library to your project:

import delivlib = require('aws-delivlib');

The next step is to add a pipeline to your app. When you define a pipeline, the minimum requirement is to specify the source repository. All other settings are optional.

const pipeline = new delivlib.Pipeline(this, 'MyPipeline', {
  // options
});

The following sections will describe the various options available in your pipeline.

Source

The only required option when defining a pipeline is to specify a source repository for your project.

repo: Source Repository (required)

The repo option specifies your source code repository for your project. You could use either CodeCommit or GitHub.

CodeCommit

To use an existing repository:

import codecommit = require('@aws-cdk/aws-codecommit');

// import an existing repository
const myRepo = ccommit.Repository.import(this, 'TestRepo', {
  repositoryName: 'delivlib-test-repo'
});

// ...or define a new repository (probably not what you want)
const myRepo = new ccomit.Repository(this, 'TestRepo');

// create a delivlib pipeline associated with this codebuild repo
new delivlib.Pipeline(this, 'MyPipeline', {
  repo: new delivlib.CodeCommitRepo(myRepo),
  // ...
});

GitHub

To connect to GitHub, you will need to store a Personal GitHub Access Token as an SSM Parameter and provide the name of the SSM parameter.

new delivlib.Pipeline(this, 'MyPipeline', {
  repo: new delivlib.GitHubRepo('<github-token-ssm-parameter-name>', 'myaccount/myrepo'),
  // ...
})

branch: Source Control Branch (optional)

The branch option can be used to specify the git branch to build from. The default is master.

new delivlib.Pipeline(this, 'MyPipeline', {
  repo: // ...
  branch: 'dev',
})

Build

The second stage of a pipeline is to build your code. The following options allow you to do customize your build environment and scripts:

buildSpec: Build Script (optional)

The default behavior will use the buildspec.yaml file from the root of your source repository to determine the build steps.

See the the buildspec reference documentation in the CodeBuild User Guide.

Note that if you don't have an "artifacts" section in your buildspec, you won't be able to run any tests against the build outputs or publish them to package managers.

If you wish, you can use the buildSpec option, in which case CodeBuild will not use the checked-in buildspec.yaml:

new delivlib.Pipeline(this, 'MyPipeline', {
  // ...
  buildSpec: {
    version: '0.2',
    phases: {
      build: {
        commands: [
          'echo "Hello, world!"'
        ]
      }
    },
    artifacts: {
      files: [ '**/*' ],
      'base-directory': 'dist'
    }
  }
});

buildImage: Build container image (optional)

The Docker image to use for the build container.

Default: the default image (if none is specified) is a custom Docker image which is bundled together with the delivlib library and called "superchain". It is an environment that supports building libraries that target multiple programming languages.

The default image is a union of the following official AWS CodeBuild images:

• node.js-8.11.0
• java-openjdk-8
• dotnet-core-2
• python-3.6.5
• ruby-2.5.1

You can use the AWS CodeBuild API to specify any Linux/Windows Docker image for your build. Here are some examples:

• codebuild.LinuxBuildImage.fromDockerHub('golang:1.11') - use an image from Docker Hub
• codebuild.LinuxBuildImage.UBUNTU_14_04_OPEN_JDK_9 - OpenJDK 9 available from AWS CodeBuild
• codebuild.WindowsBuildImage.WIN_SERVER_CORE_2016_BASE - Windows Server Core 2016 available from AWS CodeBuild
• codebuild.LinuxBuildImage.fromEcrRepository(myRepo) - use an image from an ECR repository

env: Build environment variables (optional)

Allows adding environment variables to the build environment:

new delivlib.Pipeline(this, 'MyPipeline', {
  // ...
  env: {
    FOO: 'bar'
  }
});

Other Build Options

• computeType: size of the AWS CodeBuild compute capacity (default: SMALL)
• privileged: run in privileged mode (default: false)

Tests

The third stage of a delivlib pipeline is to execute tests. Tests are executed in parallel only after a successful build and can access build artifacts as defined in your buildspec.yaml.

The pipeline.addTest method can be used to add tests to your pipeline. Test scripts are packaged as part of your delivlib CDK app.

delivlib.addTest('MyTest', {
  platform: TestablePlatform.LinuxUbuntu, // or `TestablePlatform.Windows`
  testDirectory: 'path/to/local/directory/with/tests'
});

testDirectory refers to a directory on the local file system which must contain an entry-point file (either test.ps1 or test.sh). Preferably make this path relative to the current file using path.join(__dirname, ...).

The test container will be populated the build output artifacts as well as all the files from the test directory.

Then, the entry-point will be executed. If it fails, the test failed.

Publish

The last step of the pipeline is to publish your artifacts to one or more package managers. Delivlib is shipped with a bunch of built-in publishing tasks, but you could add your own if you like.

To add a publishing target to your pipeline, you can either use the pipeline.addPublish(publisher) method or one of the built-in pipeline.publishToXxx methods. The first option is useful if you wish to define your own publisher, which is class the implements the delivlib.IPublisher interface.

Built-in publishers are designed to be idempotent: if the artifacts version is already published to the package manager, the publisher will succeed. This means that in order to publish a new version, all you need to do is bump the version of your package artifact (e.g. change package.json) and the publisher will kick in.

You can use the dryRun: true option when creating a publisher to tell the publisher to do as much as it can without actually making the package publicly available. This is useful for testing.

The following sections describe how to use each one of the built-in publishers.

npm.js

The method pipeline.publishToNpm will add a publisher to your pipeline which can publish JavaScript modules to npmjs.

The publisher will search for js/*.tgz in your build artifacts and will npm publish each of them.

To create npm tarballs, you can use npm pack as part of your build and emit them to the js/ directory in your build artifacts. The version of the module is deduced from the name of the tarball.

To use this publisher, you will first need to store an npm.js publishing token in AWS Secrets Manager and supply the secret ARN when you add the publisher.

pipeline.publishToNpm({
  npmTokenSecret: { secretArn: 'my-npm-token-secret-arn' }
});

NuGet

This publisher can publish .NET NuGet packages to nuget.org.

The publisher will search dotnet/**/*.nuget in your build artifacts and will publish each package to NuGet. To create .nupkg files, see Creating NuGet Packages. Make sure you output the artifacts under the dotnet/ directory.

To use this publisher, you will first need to store a NuGet API Key with "Push" permissions in AWS Secrets Manager and supply the secret ARN when you add the publisher.

Use pipeline.publishToNuGet will add a publisher to your pipeline:

pipeline.publishToNuGet({
  nugetApiKeySecret: { secretArn: 'my-nuget-token-secret-arn' }
});

Maven Central

This publisher can publish Java packages to Maven Central.

This publisher expects to find a local maven repository under the java/ directory in your build output artifacts. You can create one using the altDeploymentRepository option for mvn deploy (this assumes dist if the root of your artifacts tree):

$ mvn deploy -D altDeploymentRepository=local::default::file://${PWD}/dist/java

Use pipeline.publishToMaven to add this publisher to your pipeline:

pipeline.publishToMaven({
  mavenLoginSecret: { secretArn: 'my-maven-credentials-secret-arn' },
  signingKey: mavenSigningKey,
  stagingProfileId: '11a33451234521'
});

In order to configure the Maven publisher, you will need at least three pieces of information:

1. Maven Central credentials (mavenLoginSecret) stored in AWS Secrets Manager
2. GPG signing key (signingKey) to sign your Maven packages
3. Staging profile ID (stagingProfileId) assigned to your account in Maven Central.

The following sections will describe how to obtain this information.

GPG Signing Key

Since Maven Central requires that you sign your packages you will need to create a GPG key pair and publish it's public key to a well-known server:

This library includes a GPG key construct:

const mavenSigningKey = new delivlib.SigningKey(this, 'MavenCodeSign', {
  email: '[e-mail]',
  identity: 'your-identity',
  secretName: 'maven-code-sign' // secrets manager secret name
});

After you've deployed your stack once, you can go to the SSM Parameter Store console and copy the public key from the new parameter created by your stack under the specified secret name. Then, you should paste this key to any of the supported key servers (recommended: https://keyserver.ubuntu.com).

Sonatype Credentials

In order to publish to Maven Central, you'll need to follow the instructions in Maven Central's OSSRH Guide and create a Sonatype account and project via JIRA:

1. Create JIRA account
2. Create new project ticket
3. Once you have the user name and password of your Sonatype account, create an AWS Secrets Manager secret with a username and password key/value fields that correspond to your account's credentials.

Staging Profile ID

After you've obtained a Sonatype account and Maven Central project:

1. Log into https://oss.sonatype.org
2. Select "Staging Profiles" from the side bar (under "Build Promotion")
3. Click on the "Releases" staging profile that you registered
4. The URL of the page should change and include your profile ID. For example: https://oss.sonatype.org/#stagingProfiles;11a33451234521

This is the value you should assign to the stagingProfileId option.

GitHub Releases

This publisher can package all your build artifacts, sign them and publish them to the "Releases" section of a GitHub project.

This publisher relies on two files to produce the release:

• build.json a manifest that contains metadata about the release.
• CHANGELOG.md the changelog of your project, from which the release notes are extracted.

The file build.json is read from the root of your artifact tree. It should include the following fields:

{
  "name": "<project name>",
  "version": "<project version>",
  "commit": "<sha of commit>"
}

This publisher does the following:

1. Create a zip archive that contains the entire build artifacts tree under the name ${name}-${version}.zip.
2. Sign the archive using a GPG key and store it under ${name}-${version}.zip.sig
3. Check if there is already a git tag with v${version} in the GitHub repository. If there is, bail out successfully.
4. Read the CHANGELOG.md file and extract the release notes for ${version} (uses changelog-parser)
5. Create a GitHub release named v${version}, tag the specified ${commit} with the release notes from the changelog.
6. Attach the zip archive and signature to the release.

To add a GitHub release publisher to your pipeline, use the pipeline.publishToGitHub method:

pipeline.publishToGitHub({
  githubRepo: targetRepository,
  signingKey: releaseSigningKey
});

The publisher requires the following information:

• The target GitHub project (githubRepo): see instructions on how to connect to a GitHub repository. It doesn't have to be the same repository as the source repository, but it can be.
• A GPG signing key (signingKey): a delivlib.SigningKey object used to sign the zip bundle. Make sure to publish the public key to a well-known server so your users can validate the authenticity of your release (see GPG Signing Key for details on how to create a signing key pair and extract it's public key). You can either use

GitHub Pages

This publisher allows you to publish versioned static web-site content to GitHub Pages.

The publisher commits the entire contents of the docs/ directory into the root of the specified GitHub repository, and also under the ${version}/ directory of the repo (which allows users to access old versions of the docs if they wish).

NOTE: static website content can grow big. If you use the same repository for your source code and GitHub pages, your repo clones will get exponentially large due to the fact the GitHub Pages do not allow force pushing commits into a gh-pages branch. This means that we are storing each version both historically and vertically under the ${version}/ directory. It is recommended to publish docs into a separate repository.

This publisher depends on the following artifacts:

1. build.json: build manifest (see schema above)
2. docs/**: the static website contents

This is how this publisher works:

1. Read the version field from build.json
2. Clone the gh-pages branch of the target repository to a local working directory
3. Rsync the contents of docs/** both to versions/${version} and to / of the working copy. The following files will be excluded:
   • /.git/**
   • /versions/**
   • /.nojekyll
4. Commit and push to the gh-pages branch on GitHub

To add this publisher to your pipeline, use the pipeline.publishToGitHubPages method:

pipeline.publishToGitHubPages({
  githubRepo,
  sshKeySecret: { secretArn: 'github-ssh-key-secret-arn' },
  commitEmail: '[e-mail]',
  commitUsername: 'foobar',
});

In order to publish to GitHub Pages, you will need the following pieces of information:

1. The target GitHub repository (githubRepo). See instructions on how to connect to a GitHub repository. It doesn't have to be the same repository as the source repository, but it can be.
2. SSH private key (sshKeySecret) for pushing to that repository stored in AWS Secrets Manager.
3. Committer email (commitEmail) and username (commitUsername).

To obtain an SSH key for GitHub:

1. Follow this guide to produce a private/public key pair on your machine.
2. Create an AWS Secrets Manager secret and paste the private key as plaintext (not key/value).
3. Use the name of the AWS Secrets Manager secret in the sshKeySecret option.

License

This library is licensed under the Apache 2.0 License.

Changelog

10.1.1 (2020-11-23)

Bug Fixes

• pipeline-notifications: deployment fails to replace codestar notifications resource (13a0e2c)