@atomist/automation-seed

@atomist/automation-seed

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. 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, use npm to install dependencies and build the project.

$ npm install
$ npm run build

You can start up your SDM in the usual npm way.

$ npm 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, 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 the Atomist community Slack workspace.

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

Use the following package scripts to build, test, and perform other development tasks.

Command	Reason
npm install	install project dependencies
npm run build	compile, test, lint, and generate docs
npm start	start the Atomist API client
npm run autostart	run the client, refreshing when files change
npm run lint	run TSLint against the TypeScript
npm run compile	generate types from GraphQL and compile TypeScript
npm test	run tests
npm run autotest	run tests every time a file changes
npm run clean	remove files generated during the build

Release

Releases are managed by the Atomist SDM. Press the release button in the Atomist dashboard or Slack.

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