lucify-notifier

A Node.js CLI utility for sending deployment notifications to Flowdock and/or to GitHub's Deployments API.

lucify-notifier wraps a shell command and sends success or failure notifications based on the exit code of the wrapped executable.

At Lucify we use lucify-notifier as part of our CI pipeline, for example with the following deploy script in package.json:

"scripts": {
  "deploy": "lucify-notifier ecs-updater"
}

Authentication

Flowdock

The flow and the authorization to post to it are specified with the FLOWDOCK_FLOW_TOKEN environment variable. This needs to be a so called source flow_token: https://www.flowdock.com/api/sources.

GitHub

To authorize with GitHub, you need to create and install a GitHub Integration (still an early access feature) for your organization. The integration needs to have read and write access to commit statuses and deployments. With the integration installed, the following environment variables need to be set:

GITHUB_CREDENTIALS_INTEGRATION_ID="<the id of the integration>"
GITHUB_CREDENTIALS_INSTALLATION_ID="<the installation id of the above integration>"
GITHUB_CREDENTIALS_KEY="<the secret key retrieved from GH's UI when installing the integration>"

Another way to provide the GitHub credentials is store the above information as a json file in a S3 bucket. The json should have the following schema:

{
  "integration_id": "number",
  "installation_id": "number",
  "key": "string"
}

In this scenario the following environment variables need to be set:

AWS_ACCESS_KEY_ID="<credentials for accessing the above S3 object>"
AWS_SECRET_ACCESS_KEY="<credentials for accessing the above S3 object>"

The location of the credentials file can be provided as an environment variable

GITHUB_S3_CREDENTIALS="s3://<bucket>/<key>"

or specified as github.s3_credentials in the configuration file described below.

Configuration

lucify-notifier has three sources for its configuration, which are in order of preference:

1. environment variables
2. configuration file
3. defaults

There are quite a few settings, here's the complete json schema with their defaults:

{
  github: {
    // these correspond directly
    // to the options in
    // https://developer.github.com/v3/repos/deployments/#create-a-deployment
    deploymentOptions: {
      required_contexts: [],
      task: 'deploy',
      auto_merge: false,
      payload: '',
      description: '',
      transient_environment: false,
      production_environment: process.env.NODE_ENV === 'production',
    },
    // either credentials OR s3_credentials are required
    credentials: {
      integration_id: 0,
      installation_id: 0,
      key: '',
    },
    s3_credentials: '',
  },
  flowdock: {
    flow_token: '', // required
    author: {
      name: '',
      email: '', // required
    },
  },
  deployment: {
    branch: {
      ref: 'master',
      repository: '', // required
      owner: '', // username or organization, required
    },
    environment: process.env.NODE_ENV,
    committer: '', // required, explained in more detail below
    url: '', // explained in more detail below
    build_url: '', // explained in more detail below
    commit_message: '', // explained in more detail below
  },
  build_command: '', // defaults to the one given on the command-line
  decryption_key: '',
  aws_temporary: '',
}

deployment.committer

This is crucial for the GitHub notifications. It has to correspond to a GitHub user who has authorization to create deployments in the specified repository. More information about integrations acting on behalf of users can be found on https://developer.github.com/early-access/integrations/authentication/#requesting-an-access-token-on-behalf-of-a-user.

If flowdock.author.name is undefined, it defaults to deployment.committer.

deployment.url

Used in the notification content. Should be specified if the deployment can be viewed in the browser. In GitHub's case, if specified, it will show a view deployment button in pull requests. In flowdock, it's part of the notification payload.

deployment.build_url

Used in the notification content. Should point to a url where a log of the build process can be viewed, such as a CI/CD service. In GitHub's case, if specified, it will show a deployed link in PRs. In flowdock, it's part of the notification payload.

deployment.commit_message

Used in the notification content. If not specified and the current working directory is a git repository, then the latest commit message from that repository is used.

Environment variables

Each of the options can be specified with an environment variable. The variable names correspond to the above schema, so that , for example, flowdock.author.name would be looked from FLOWDOCK_AUTHOR_NAME and decryption_key from DECRYPTION_KEY.

Configuration file

If a file named lucify-notifier.config.js|json is found in the directory where lucify-notifieris executed, it is assumed to contain a json object with the schema specified above. A .js file should export the json with

module.exports = <json>

Here's an example of a typical configuration file:

const envVars = process.env;
const environment = envVars.NODE_ENV === 'production' ? 'production' : 'staging';
const statusUrl = `https://${environment === 'production' ? '' : 'staging.'}foo.io/status`;
module.exports = {
  deployment: {
    branch: {
      ref: envVars.CIRCLE_BRANCH,
      owner: envVars.CIRCLE_PROJECT_USERNAME,
      repository: envVars.CIRCLE_PROJECT_REPONAME,
    },
    committer: envVars.CIRCLE_USERNAME,
    build_url: envVars.CIRCLE_BUILD_URL,
    url: statusUrl,
    environment,
  },
  github: {
    s3_credentials: 's3://<bucket>/<aws_credentials_key>',
    deploymentOptions: {
      transient_environment: true,
    },
  },
  flowdock: {
    flow_token: '',
    author: {
      email: '[email protected]',
    },
  },
  decryption_key: '',
}

Credential decryption

In general lucify-notifier tries to not affect the executable it wraps in any way. All the environment variables are passed on, with one exception: if the AWS_TEMPORARY option is specified, then it is assumed that it constains encrypted temporary AWS credentials that should be decrypted and provided as environment variables for the the wrapped executable.

The mapping from the decrypted AWS_TEMPORARY json to environment variables is:

{
  'accessKeyId': 'AWS_ACCESS_KEY_ID',
  'secretAccessKey': 'AWS_SECRET_ACCESS_KEY',
  'sessionToken': 'AWS_SESSION_TOKEN',
}

This feature serves a very specific purpose: when launching production deployments in CircleCI via its REST API, the extra environment variables specified in the request, including the aws credentials, are visible in the build log output. To prevent revealing them, one can then specify the DECRYPTION_KEY environment variable in the CircleCI project settings (these are never visible) and provide an encrypted json object in the AWS_TEMPORARY variable. If DECRYPTION_KEY is not defined, it defaults to AWS_ACCESS_KEY_ID.

The encryption and decryption details are a bit involved, but they use aes-256-gcm symmetric authenticated cryptography. See utils.ts for the code.