Atomist can now be put to work: reporting on events in your development systems, creating projects, editing code, managing issues, and generally tying your whole development process together. Let’s kick things off by connecting some of your existing code repositories to your chat channels. After that, we’ll use the Atomist Bot to create a new project for us using a generator.
Using Atomist on existing projects¶
You almost certainly have many existing projects that you would like
Atomist’s help keeping track of. To get Atomist’s help with an
existing GitHub repository, simply invite the Atomist Bot to a channel
where you discuss that repository. You can invite the Atomist Bot to
a channel just as you would invite any other user, e.g., by using the
/invite @atomist command. Once the Atomist Bot is in the channel,
you can tell the Atomist Bot what repository to associate with the
channel by sending it the
repo message. The
repo command takes a
single argument, the name of the repository you want to associate with
the channel. You supply just the name of the repository, not
including the repository owner since the Atomist Bot already knows
what GitHub organization is associated with your Slack team.
@atomist repo REPOSITORY_NAME
If you are working through these steps in
the Atomist Community Slack, associations can only be
made with repositories in the
atomist GitHub organization.
At any time you can ask the Atomist Bot to tell you what repository is
associated with the current channel by sending it the
The Atomist Bot will respond with the repositories linked to the current channel, providing links to the repositories and buttons to allow you to quickly un-link the channel and repository.
You can link more than one repository to a chat channel if you have a set of related repositories that are all discussed in a single channel.
While you can also link a single repository to multiple chat channels, repository and build messages for that repository will only be sent to one of the channels, so we do not recommend it.
GitHub and CI notifications¶
Once the association between a repository and chat channel is made, the Atomist Bot will begin reporting on activity in the associated repository. You can see these messages by committing and pushing a change to the repository. The Atomist Bot will post a message to the chat channel detailing the commits in the push and, if you have connected Atomist with your CI system, build status, updating it as the build goes from started to successful.
Changing GitHub from Slack¶
Getting well-formatted message in Slack about what is happening to your project on GitHub is nice, but it only scratches the surface of what Atomist can do. In addition to passively receiving and then displaying GitHub events, Atomist can generate and modify code and open issues and PRs, all without you ever having to leave Slack. To demonstrate this capability, you will use the Atomist Bot to create a GitHub Issue.
You can open GitHub Issues without leaving chat by sending a
issue message to the Atomist Bot. When running commands like this,
the Atomist Bot is aware of the context in which it is asked to run
the skill. This allows the Atomist Bot to collect less information in
certain situations. What does this mean? This can be illustrated by
running the same command in two different channels. First, run the
create issue command in the
#general channel, which is not
associated with any repository, of your Slack team.
@atomist create issue
The Atomist Bot responds in a thread, collecting the information it needs to create the issue.
#general channel is not linked to a specific GitHub
repository, the Atomist Bot must ask you in what repository you
want to create the issue.
Compare this to sending the same
create issue message to the Atomist
Bot in a channel associated with a repository. As usual, your Atomist
Bot will start a thread to collect all the information necessary it
needs to complete the request, but it will not ask you to enter a
Since there is already an association between the channel in which the message was sent and a repository, the Atomist Bot will automatically pass the associated repository along with the request. No need for you to enter it in!
With either approach, once you have entered all the needed information, your Atomist Bot will respond with a summary and the option to submit or cancel.
Click the “Submit” button and Atomist will create the issue and then respond back in the channel where the thread started.
But that’s not where the interaction stops. The Atomist Bot will also post a message in the repository channel containing a summary of the newly created issue and some buttons for common actions taken on issues: assign it someone, add a label, add a comment, etc.
Go ahead and click on the link to see the issue on GitHub.
Now head back to the repository channel in Slack and click on the “Bug” button to add the “bug” label to the issue:
We see the Atomist Bot responding that it has successfully edited the issue. Let’s make sure. Click on the link to open up the issue in GitHub.
We can see that Atomist, as us, has labeled the issue a bug, just as we asked.
Now imagine that you are another team member who has noticed this new issue and wants to add a comment from inside GitHub. Using the GitHub web interface, add a comment and click the “Comment” button.
You will see a new message in the
#sprocket channel from the Atomist
Bot notifying you that the issue has been updated.
After connecting Atomist and GitHub, we can see GitHub events in Slack, take action on them, and see the result in GitHub and Slack.
Create a new project¶
You can ask the Atomist Bot to create a new project for you either
through a direct message or by addressing the Bot in a channel it has
been invited to. For our purposes, we will assume you are starting
the conversation in your Slack team’s
#general channel, which the
Atomist Bot joins when invited to your Slack team, and that the
Atomist Bot is named
@atomist. In the
#general channel, type the
The Atomist Bot will reply with a list of project generators that it can use on your behalf to create a new project in GitHub. The Atomist Bot will respond with a list of project generators something like the following.
While the full list of project generators can be useful if you are just browsing, we want to create a Spring Boot REST service, so we can narrow down the list by providing a search term, “spring” in this case.
@atomist generators spring
This time the Atomist Bot will respond with a list of project generators matching the search term, including the NewSpringBootRestService generator.
Click on the “Generate project” button to begin the process of creating your new project.
The Atomist Bot will respond with a message telling you what project generator you created and then start a thread off that message to gather the information it needs to generate the project. Click now on the “1 reply” link below the message to open up the thread in Slack. You will see that the Atomist Bot has asked you a question in the thread.
Type in a name for your new project and press
Enter. The project
name must be a valid GitHub repository name, containing only letters,
numbers, dashes (
-), and underscores (
_). Since the project name
is the only required input parameter for the
NewSpringBootRestService generator, the Atomist Bot will respond
with a message showing the project name you entered and the default
values for all the other input parameters.
If the name of the project you created is longer than 21 characters, the channel name will be truncated to 21 characters, the maximum length channel name Slack allows.
You can change the value for any of the parameters by typing in
<parameter> <value> before you click on
Now click on
Generate project and you’ll see several things happen:
- In the thread, the Atomist Bot will announce “One moment while I run the generator.”
- Atomist will go and create the repository for you in the GitHub account you previously authorized.
- The Atomist Bot will announce that it has “Successfully generated
your project” back in the main channel where the project creation
thread was started in, in our case that would be
#general. The announcement will contain a link to the newly generated project.
- Atomist will create a new channel in your Slack team for the new project, that will also be associated with the project’s repository so when you want to work on that project, you do it in that channel.
If you are working through these steps in
the Atomist Community Slack, the new repository will
be created under your personal GitHub account and the Atomist Bot
will not create a Slack channel for the repository. You can see
example GitHub and CI notifications in channels associated with
the Atomist open source project repositories like
Here’s what the successful project creation message looks like:
Click on the project link to see your project in GitHub.
Clone your new repository from GitHub and you will have a new, working project courtesy of Atomist.