This repository contains examples demonstrating use of the Atomist API. 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.
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
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
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
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
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 firstname.lastname@example.org: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
$ `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
--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
To start the client, run the following command:
$ npm run autostart
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, 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
General support questions should be discussed in the
channel in our community Slack team
If you find a problem, please create an issue.
You will need to install node to build and test this project.
Build and Test
||install all the required packages|
||lint, compile, and test|
||start the Atomist automation client|
||run the client, refreshing when files change|
||run tslint against the TypeScript|
||run tests and ensure everything is working|
||run tests continuously|
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
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.