Integrates with the GitHub deployments API and Flowdock
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:
``json`
"scripts": {
"deploy": "lucify-notifier ecs-updater"
}
environment variable. This needs to be a so called source :
https://www.flowdock.com/api/sources.$3
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:`shell
GITHUB_CREDENTIALS_INTEGRATION_ID=""
GITHUB_CREDENTIALS_INSTALLATION_ID=""
GITHUB_CREDENTIALS_KEY=""
`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:
json
{
"integration_id": "number",
"installation_id": "number",
"key": "string"
}
`In this scenario the following environment variables need
to be set:
shell
AWS_ACCESS_KEY_ID=""
AWS_SECRET_ACCESS_KEY=""
`The location of the credentials file can be provided as an environment
variable
shell
GITHUB_S3_CREDENTIALS="s3:///"
`
or specified as 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:
`javascript
{
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: '',
}
`$3
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
is undefined, it defaults to deployment.committer.$3
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.
$3
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.
$3
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.
$3
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 .
$3
If a file named lucify-notifier.config.js|json
is found in the directory where is executed,
it is assumed to contain a json object with the schema
specified above. A .js file should export the json with`javascript
module.exports =
`Here's an example of a typical configuration file:
javascript
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:///',
deploymentOptions: {
transient_environment: true,
},
},
flowdock: {
flow_token: '',
author: {
email: 'deploy@foo.com',
},
},
decryption_key: '',
}
`Credential decryption
In general
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:
`typescript
{
'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
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