@atomist-seeds/automation-client

This repository contains examples demonstrating use of the Atomist API for software. You will find examples illustrating:

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

These examples use the @atomist/automation-client node module to implement a local client that connects to the Atomist API for software. See the Atomist documentation for more information about Atomist, software delivery machines (SDM), and the Atomist API for software.

Prerequisites

Before you can run this project, you will need an Atomist workspace linked to a Slack workspace. See the Atomist Getting Started Guide for instructions on how to get an Atomist workspace and connect it to your source code repositories, continuous integration, chat platform, etc.

You will also need several other prerequisites to successfully run this project. See the Atomist Developer Guide for instructions on setting up your development environment. Briefly, you will need Git, Node.js, and the Atomist CLI installed and properly configured on your system.

Running

Once the prerequisites are met on your system, you can use the Atomist CLI to install dependencies, build the project, and start the client.

$ atomist start

The Atomist API Client documentation has more complete instructions for running an SDM or other Atomist API client.

Using

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][nop-handler], 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.

To see this handler in action, you must first link a GitHub repository to a Slack channel. You can do this by inviting the Atomist bot to the channel you want to link, sending it the message "repo", i.e., @atomist repo, and answering its questions.

Support

General support questions should be discussed in the #support channel in the Atomist community Slack workspace.

If you find a problem, please create an issue.

Development

You will need to install Node.js to build and test this project.

Build and test

Install dependencies.

$ npm install

Use the build package script to compile, test, lint, and build the documentation.

$ npm run build

Release

Releases are handled via the Atomist SDM. Just press the 'Approve' button in the Atomist dashboard or Slack.

---

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