Git Host Access Credentials

This page describes how to create credentials for your Git host (GitHub, GitLab, Bitbucket, or Azure DevOps)

that Atlantis will use to make API calls.

Create an Atlantis user (optional)

We recommend creating a new user named @atlantis (or something close) or using a dedicated CI user.

This isn't required (you can use an existing user or github app credentials), however all the comments that Atlantis writes will come from that user so it might be confusing if its coming from a personal account.

Example Comment

An example comment coming from the @atlantisbot user

Generating an Access Token

Once you've created a new user (or decided to use an existing one), you need to generate an access token. Read on for the instructions for your specific Git host:

GitHub user

WARNING

Your Atlantis user must also have "Write permissions" (for repos in an organization) or be a "Collaborator" (for repos in a user account) to be able to set commit statuses: Atlantis status

GitHub app

WARNING

Available in Atlantis versions newer than 0.13.0.

The installation suggestions differ if you're installing into a user account or an organization.

User

  • Start Atlantis with fake github username and token (atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST)

  • Visit https://$ATLANTIS_HOST/github-app/setup and click on Setup to create the app on Github. You'll be redirected back to Atlantis

  • A link to install your app, along with its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link.

  • Create a file with the contents of the GitHub App Key, e.g. atlantis-app-key.pem

  • Restart Atlantis with new flags: atlantis server --gh-app-id <your id> --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret <your secret> --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST.

    NOTE: You can also create a config file instead of using flags. See Server Configuration.

WARNING

Only a single installation per GitHub App is supported at the moment.

Organization

Follow the steps for User installation above and in addition:

  • Go to the users' Settings
  • Click Developer Settings in the left menu
  • With GitHub Apps chosen on the left, click Edit on the App
  • Click Advanced in the left menu
  • Click Transfer ownership and enter the name of the GitHub App and the name of the organization
  • Click Complete transfer

As an administrator of the organization. Visit the Settings.

  • Click GitHub Apps
  • Click Edit on the App
  • Choose Install App in the left menu
  • Click Install on the App,
  • Enable the App for one or more repositories (you can change this later) and click Install

Since Atlantis currently only supports one installation, and is now installed on both the user and the organisation, it needs to be uninstalled on the user account.

  • Go to the users' Settings.
  • Click Applications
  • On the Atlantis GitHub app, click Configure
  • Click Uninstall and confirm

GitLab

Bitbucket Cloud (bitbucket.org)

Bitbucket Server (aka Stash)

  • Click on your avatar in the top right and select Manage account
  • Click Personal access tokens in the sidebar
  • Click Create a token
  • Name the token atlantis
  • Give the token Read Project permissions and Write Pull request permissions
  • Click Create and record the access token

Azure DevOps

Next Steps

Once you've got your user and access token, you're ready to create a webhook secret. See Creating a Webhook Secret.