Connect Atomist to GitHub

To help streamline your development flow, Atomist needs access to your source code. Currently Atomist supports integrating with GitHub.com.

Atomist works with GitHub.com. GitHub Enterprise is not currently supported.

There are two kinds of authorization Atomist asks for to work with GitHub:

  • GitHub Account Authorization: this authorization determines the GitHub individual account or GitHub organization that Atomist will connect to your Slack team. For example, if you want to receive notifications and take actions in your team’s primary GitHub organization, you should select that organization when authorizing Atomist to GitHub. If you want to use Atomist with your individual account, then you should select your user when authorizing Atomist to GitHub.

    Depending on the third-party application access policy in your GitHub organization, your GitHub user may need to have the “Owner” role in the organization or, if not, you may have to request access to authorize Atomist.

  • GitHub User Authorization: this authorization is done so that commands and actions you ask the Atomist Bot to perform on your behalf are carried out as your GitHub user. For example, if you ask the Atomist Bot to create a GitHub issue, it needs to be authorized to create the issue as you. Every person in your Slack team who wants to ask the Atomist Bot to perform actions against GitHub will need to authorize their GitHub user in this way.

GitHub Account Authorization

This section will walk you through the GitHub account authorization process. You can perform these steps in any Slack channel that the Atomist Bot has been invited to, or you can directly message the Atomist Bot. By default the Atomist Bot is named @atomist and these instructions assume that is its name in your Slack team. If the Atomist Bot has a different user name in your Slack team, address messages to that user.

First, ask the Atomist Bot about your GitHub authorizations.

@atomist github

If this Slack team does not have a GitHub Account authorized, the Atomist Bot will show a message requesting you to authorize.

GitHub Account Auth Message

You will see messages for both GitHub account authorization (the first message) and GitHub user authorization (the second message). First, let’s do the account authorization. Click on the “Authorize GitHub Account” link in the message. You will be redirected to the GitHub authorization page in your browser.

GitHub Account OAuth

For information on the permissions requested, see GitHub Permissions.

Click the “Authorize application” button to authorize Atomist and you will then be redirected back to your Slack team in the browser.

If you are not a member of any GitHub organizations, your individual GitHub account will be automatically selected, and you will not see any organizations listed. If you are a member of one or more GitHub organizations, after authorizing Atomist, you will receive a direct message in Slack from the Atomist Bot asking whether to use your individual GitHub account or one of your organizations as the GitHub account to associate with Atomist.

Select GitHub Account

Select the GitHub account (your individual account or an organization) to associate with Atomist by clicking its button. Once selected, the Atomist Bot will show a confirmation message in Slack.

GitHub Account Authorized Message

Congratulations, your GitHub account is now authorized.

GitHub User Authorization

Now, let’s associate your GitHub user with your Slack user. To do this, scroll back in the history or enter @atomist github to show the GitHub authorization message again.

GitHub User Authorization Message

Click on the “Authorize GitHub User” link in the message. You will be redirected to the GitHub authorization page in your browser.

GitHub User OAuth

Click the “Authorize application” button to authorize Atomist and you will then be redirected back to your Slack team in the browser, where you will see a confirmation message.

GitHub User Authorized

If you use a native client for Slack, you can close the Slack browser window and go back to your preferred Slack client. If you use your web browser to access Slack, you will likely have several Slack tabs or windows open at this point. Feel free to close all but one.

Now that you have have connected Atomist in your Slack team and GitHub account, you can start using it. Skip to the Atomist Bot section to get going now. Atomist can also automate CI notifications and actions. To do so, go through the steps in Connect Atomist to CI.