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
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.
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.
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.
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
/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.
General support questions should be discussed in the
channel in the Atomist community Slack workspace.
If you find a problem, please create an issue.
You will need to install Node.js to build and test this project.
Build and test
$ npm install
build package script to compile, test, lint, and build the
$ npm run build
Releases are handled via the Atomist SDM. Just press the 'Approve' button in the Atomist dashboard or Slack.