@mumoshu/brigade-automation

This repository contains the atomist automation for Brigade

You will find implementaions of:

• Bot commands using command handlers
• Responding to DevOps events, e.g., commits pushed to a repository, using event handlers

These implementations use the @atomist/automation-client node module to implement a local client that connects to the Atomist API.

Atomist then acts as the webhook gateway for brigade-automation, so that the automation itself can indirectly receive webhook events without being exposed to the Internet.

This results in e.g. a more secure CI/CD pipeline because then you don't need to expose your K8S API server to the Internet for access from your CI service like Travis, CircleCI, and so on.

Development

Using edge atomist libraries

This app uses the edge atomist library to leverage very recent features of it(as of Mar. 2018).

To use the edge library, it must be reffered in your package.json like:

"dependencies": {
    "@atomist/automation-client": "^0.6.7-20180304171840",
    "app-root-path": "^2.0.1"
  },

Also point npm to fetch edge atomist libraries from atomist's development npm repository:

npm config set @atomist:registry https://atomist.jfrog.io/atomist/api/npm/npm-dev/

npm install

See https://atomist.jfrog.io/atomist/webapp/#/artifacts/browse/tree/General/npm-dev-local/@atomist/automation-client/-/@atomist/automation-client-0.6.7-20180304171840.tgz for more info about setting jfrog as a npm repository.

Prerequisites

Below are brief instructions on how to get started running this project yourself. If you just want to use the functionality this project provides, see the Atomist documentation. For more detailed information on developing automations, see the Atomist Developer Guide.

Slack and GitHub

Atomist automations work best when connected to Slack and GitHub. If you do not have access to a Slack team and/or GitHub organization, it is easy to create your own.

• Create a Slack team
• Create a GitHub organization

In your Slack team, install the Atomist app in Slack, click the button below.

Once installed, the Atomist bot will guide you through connecting Atomist, Slack, and GitHub.

If you'd rather not set up your own Slack team and GitHub organization, please reach out to members of Atomist in the #support channel of atomist-community Slack team. You'll receive an invitation to a Slack team and GitHub organization that can be used to explore this new approach to writing and running automations.

The Slack team ID for atomist-playground is T7GMF5USG.

Node.js

You will need to have Node.js installed. To verify that the right versions are installed, please run:

$ node -v
v8.4.0
$ npm -v
5.4.1

The node version should be 8 or greater and the npm version should be 5 or greater.

Cloning the repository and installing dependencies

To get started run the following commands to clone the project, install its dependencies, and build the project:

$ git clone git@github.com:atomist/automation-seed-ts.git
$ cd automation-seed-ts
$ npm install
$ npm run build

Configuring your environment

If this is the first time you will be running an Atomist API client locally, you should first configure your system using the atomist script:

$ `npm bin`/atomist config

The script does two things: records what Slack team you want your automations running in and creates a GitHub personal access token with "repo" and "read:org" scopes.

The script will prompt you for you Slack team ID, or you can supply it using the --slack-team TEAM_ID command-line option. You must run the automations in a Slack team of which you are a member. You can get the Slack team ID by typing team in a DM to the Atomist bot.

The script will prompt you for your GitHub credentials. It needs them to create the GitHub personal access token. Atomist does not store your credentials and only writes the generated token to your local machine.

The Atomist API client authenticates using a GitHub personal access token. The Atomist API uses the token to confirm you are who you say you are and are in a GitHub organization connected to the Slack team in which you are running the automations. In addition, it uses the token when performing any operations that access the GitHub API.

Starting up the automation-client

You can run this repository locally, allowing you to change the source code of this project and immediately see the effects in your environment with the following command

$ npm run autostart

To run in a more traditional manner, build the project and then simple start it.

$ npm run build
$ npm start

To build a Docker image, run:

$ docker build -t mumoshu/brigade-automation:VERSION .

To download and run the Docker image of this project, run the following command

$ cat << EOS > .envrc
export GITHUB_TOKEN=YOUR_TOKEN
export ATOMIST_TEAM=YOUT_TEAM
EOS

$ direnv allow .

$ docker run --rm -e GITHUB_TOKEN -e ATOMIST_TEAM \
    mumoshu/brigade-automation:VERSION

replacing YOUR_TOKEN and TEAM_ID with the token and team ID from your ~/.atomist/client.config.json created by the atomist config command and VERSION with the latest release of this repo. Note that this will not be running any code from your local machine but the code in the Docker image.

To run the Docker image in a Kubernetes cluster, you can use the deployment spec from this repository, replacing YOUR_TOKEN, TEAM_ID (twice!), and VERSION in the spec as above in the Docker run command, and running the following command

$ kubectl create -f automation-seed-deployment.json

An alternative way is to use helm chart for installing the deployment:

# Replace $region, $awsaccount and $keyid according to your setup
$ cat << EOF > .sops.yaml
creation_rules:
- kms: "arn:aws:kms:$region:$awsaccount:key/$keyid"
EOF
$ cat << EOF > secrets.yaml.cleartext
env:
  GITHUB_TOKEN: $GITHUB_TOKEN
  ATOMIST_TEAM: $ATOMIST_TEAM
EOF
$ sops -e secrets.yaml.cleartext > secrets.yaml
$ helm-secrets install ./charts/brigade-automation -f secrets.yaml -n your-brigade-project-ns

Invoking a command handler from Slack

This project contains the code to create and respond to a simple hello world bot command. The code that defines the bot command and implements responding to the command, i.e., the command handler, can be found in HelloWorld.ts. Once you have your local automation client running (the previous step in this guide), you can invoke the command handler by sending the Atomist bot the command as a message. Be sure the Atomist bot is in the channel before sending it the message.

/invite @atomist
@atomist hello world

Once you've submitted the command in Slack, you'll see the incoming and outgoing messages show up in the logs of your locally running automation-client. Ultimately, you should see the response from the bot in Slack.

Feel free to modify the code in the HelloWorld command handler, Node.js will automatically reload the client, and see what happens!

Triggering an event handler

While command handlers respond to commands you send the Atomist bot, event handlers take action when different types of events occur in your development and operations environment. Some examples of events are commits pushed to a repo, or a CI build that fails, or an instance of a running service that becomes unhealthy. Example responses to those events are showing the commits in a Slack message, automatically restarting the build, and triggering a PagerDuty alert, respectively.

The sample event handler in this project, NotifyOnPush, will notice when someone pushes new commits to a repository in the GitHub organization and send a notice of that push to all Slack channels associated with that repository.

If you have followed the instructions above and are running these automations against the atomist-playground Slack team and GitHub organization, go ahead and edit the notify-on-push repository by adding some text to its README. Once you have saved your changes, you should see that event appear in the console logs of your locally running automation client, followed by a log of the actions the event handler is taking. Once those actions are complete, you should see a new message in the #notify-on-push channel in the atomist-playground Slack team.

Support

General support questions should be discussed in the #support channel in our community Slack team at atomist-community.slack.com.

If you find a problem, please create an issue.

Development

You will need to install node to build and test this project.

Build and Test

Command	Reason
npm install	install all the required packages
npm run build	lint, compile, and test
npm start	start the Atomist automation client
npm run autostart	run the client, refreshing when files change
npm run lint	run tslint against the TypeScript
npm run compile	compile all TypeScript into JavaScript
npm test	run tests and ensure everything is working
npm run autotest	run tests continuously
npm run clean	remove stray compiled JavaScript files and build directory

Release

To create a new release of the project, update the version in package.json and then push a tag for the version. The version must be of the form M.N.P where M, N, and P are integers that form the next appropriate semantic version for release. The version in the package.json must be the same as the tag. For example:

$ npm version 1.2.3
$ git tag -a -m 'The ABC release' 1.2.3
$ git push origin 1.2.3

The Travis CI build (see badge at the top of this page) will publish the NPM module and automatically create a GitHub release using the tag name for the release and the comment provided on the annotated tag as the contents of the release notes.

Publishiung the helm chart

The chart is available at the chart repository: https://mumoshu.github.io/brigade-automation

To publish a new revision of the helm chart, run:

# Install the required plugin: https://github.com/technosophos/helm-github
$ helm plugin install https://github.com/technosophos/helm-github

# Publish it
$ scripts/publish-chart

---

Created by Atomist. Need Help? Join our Slack team.