Skip to content

Commit

Permalink
Update Bitbucket server docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@lkysow
lkysow committed Jul 24, 2018
1 parent da236e9 commit ddbf967
Show file tree
Hide file tree
Showing 4 changed files with 148 additions and 50 deletions.
35 changes: 34 additions & 1 deletion runatlantis.io/docs/deployment.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Once you've decided where to host Atlantis you need to add that URL as a webhook
to your Git host so that Atlantis gets notified about pull request events.
See the instructions for your specific provider below:

### GitHub Webhook
### GitHub/GitHub Enterprise Webhook
If you already have a GitHub organization we recommend installing the webhook at the **organization level** rather than on each repository, however both methods will work.

::: tip
Expand Down Expand Up @@ -78,6 +78,19 @@ If you're using GitLab, navigate to your project's home page in GitLab
- Click **Save**
<img src="../guide/images/bitbucket-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px">

### Bitbucket Server (aka Stash) Webhook
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Create webhook**
- Enter "Atlantis" for **Name**
- set **URL** to `http://$URL/events` (or `https://$URL/events` if you're using SSL) where `$URL` is where Atlantis is hosted. **Be sure to add `/events`**
- Double-check you added `/events` to the end of your URL.
- Set **Secret** to a random key (https://www.random.org/strings/). You'll need to pass this value to the `--bitbucket-webhook-secret` flag when you start Atlantis
- Under **Repository** select **Push**
- Under **Pull Request**, select: Opened, Modified, Merged, Declined, Deleted and Comment added
- Click **Save**<img src="../guide/images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px;">

## Create an access token for Atlantis
We recommend using a dedicated CI user or creating a new user named **@atlantis** that performs all API actions, however for testing,
you can use your own user. Here we'll create the access token that Atlantis uses to comment on the pull request and
Expand All @@ -101,6 +114,14 @@ set commit statuses.
- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
- copy the access token

### Create a Bitbucket Server (aka Stash) Personal Access Token
- 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 copy the access token

## Start Atlantis
Now you're ready to start Atlantis! The exact command depends on your Git host:

Expand Down Expand Up @@ -157,6 +178,18 @@ atlantis server \
--repo-whitelist="$REPO_WHITELIST"
```

### Bitbucket Server (aka Stash)
```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--bitbucket-webhook-secret="$SECRET" \
--bitbucket-base-url="$BASE_URL" \
--repo-whitelist="$REPO_WHITELIST"
```

Where
- `$URL` is the URL that Atlantis can be reached at
- `$USERNAME` is the GitHub/GitLab/Bitbucket username you generated the token for
Expand Down
161 changes: 113 additions & 48 deletions runatlantis.io/guide/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Getting Started
These instructions are for running Atlantis locally so you can test it out against
These instructions are for running Atlantis **locally on your own computer** so you can test it out against
your own repositories before deciding whether to install it more permanently.

::: tip
Expand Down Expand Up @@ -43,7 +43,7 @@ URL="https://{YOUR_HOSTNAME}.ngrok.io"
GitHub and GitLab use webhook secrets so clients can verify that the webhooks came
from them.
::: warning
Bitbucket Cloud (bitbucket.org) doesn't use webhook secrets so if you're using Bitbucket you can skip this
Bitbucket Cloud (bitbucket.org) doesn't use webhook secrets so if you're using Bitbucket Cloud you can skip this
however you should whitelist Bitbucket IPs as a precaution.
:::
Create a random string of any length (you can use [http://www.unit-conversion.info/texttools/random-string-generator/](http://www.unit-conversion.info/texttools/random-string-generator/))
Expand All @@ -55,67 +55,106 @@ SECRET="{YOUR_RANDOM_STRING}"
## Add Webhook
Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bitbucket repo:

### GitHub
- Go to your repo's settings
- Select **Webhooks** or **Hooks** in the sidebar
- Click **Add webhook**
- set **Payload URL** to your ngrok url with `/events` at the end. Ex. `https://c5004d84.ngrok.io/events`
- double-check you added `/events` to the end of your URL.
- set **Content type** to `application/json`
- set **Secret** to your random string
- select **Let me select individual events**
- check the boxes
- **Pull request reviews**
- **Pushes**
- **Issue comments**
- **Pull requests**
- leave **Active** checked
- click **Add webhook**

### GitLab
- Go to your repo's home page
- Click **Settings > Integrations** in the sidebar
- set **URL** to your ngrok url with `/events` at the end. Ex. `https://c5004d84.ngrok.io/events`
- double-check you added `/events` to the end of your URL.
- set **Secret Token** to your random string
- check the boxes
- **Push events**
- **Comments**
- **Merge Request events**
- leave **Enable SSL verification** checked
- click **Add webhook**
### GitHub or GitHub Enterprise
<details>
<summary>Expand</summary>
<ul>
<li>Go to your repo's settings</li>
<li>Select <strong>Webhooks</strong> or <strong>Hooks</strong> in the sidebar</li>
<li>Click <strong>Add webhook</strong></li>
<li>set <strong>Payload URL</strong> to your ngrok url with <code>/events</code> at the end. Ex. <code>https://c5004d84.ngrok.io/events</code></li>
<li>double-check you added <code>/events</code> to the end of your URL.</li>
<li>set <strong>Content type</strong> to <code>application/json</code></li>
<li>set <strong>Secret</strong> to your random string</li>
<li>select <strong>Let me select individual events</strong></li>
<li>check the boxes
<ul>
<li><strong>Pull request reviews</strong></li>
<li><strong>Pushes</strong></li>
<li><strong>Issue comments</strong></li>
<li><strong>Pull requests</strong></li>
</ul>
</li>
<li>leave <strong>Active</strong> checked</li>
<li>click <strong>Add webhook</strong></li>
</ul>
</details>

### GitLab or GitLab Enterprise
<details>
<summary>Expand</summary>
<ul>
<li>Go to your repo's home page</li>
<li>Click <strong>Settings &gt; Integrations</strong> in the sidebar</li>
<li>set <strong>URL</strong> to your ngrok url with <code>/events</code> at the end. Ex. <code>https://c5004d84.ngrok.io/events</code></li>
<li>double-check you added <code>/events</code> to the end of your URL.</li>
<li>set <strong>Secret Token</strong> to your random string</li>
<li>check the boxes
<ul>
<li><strong>Push events</strong></li>
<li><strong>Comments</strong></li>
<li><strong>Merge Request events</strong></li>
</ul>
</li>
<li>leave <strong>Enable SSL verification</strong> checked</li>
<li>click <strong>Add webhook</strong></li>
</ul>
</details>

### Bitbucket Cloud (bitbucket.org)
- Go to your repo's home page
- Click **Settings** in the sidebar
- Click **Webhooks** under the **WORKFLOW** section
- Click **Add webhook**
- Enter "Atlantis" for **Title**
- set **URL** to your ngrok url with `/events` at the end. Ex. `https://c5004d84.ngrok.io/events`
- double-check you added `/events` to the end of your URL.
- Keep **Status** as Active
- Don't check **Skip certificate validation** because NGROK has a valid cert.
- Select **Choose from a full list of triggers**
- Under **Repository** **un**check everything
- Under **Issues** leave everything **un**checked
- Under **Pull Request**, select: Created, Updated, Merged, Declined and Comment created
- Click **Save**
<img src="./images/bitbucket-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px">
<details>
<summary>Expand</summary>
<ul>
<li>Go to your repo's home page</li>
<li>Click <strong>Settings</strong> in the sidebar</li>
<li>Click <strong>Webhooks</strong> under the <strong>WORKFLOW</strong> section</li>
<li>Click <strong>Add webhook</strong></li>
<li>Enter "Atlantis" for <strong>Title</strong></li>
<li>Set <strong>URL</strong> to your ngrok url with <code>/events</code> at the end. Ex. <code>https://c5004d84.ngrok.io/events</code></li>
<li>Double-check you added <code>/events</code> to the end of your URL.</li>
<li>Keep <strong>Status</strong> as Active</li>
<li>Don't check <strong>Skip certificate validation</strong> because NGROK has a valid cert.</li>
<li>Select <strong>Choose from a full list of triggers</strong></li>
<li>Under <strong>Repository</strong><strong>un</strong>check everything</li>
<li>Under <strong>Issues</strong> leave everything <strong>un</strong>checked</li>
<li>Under <strong>Pull Request</strong>, select: Created, Updated, Merged, Declined and Comment created</li>
<li>Click <strong>Save</strong><img src="./images/bitbucket-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px;"></li>
</ul>
</details>

### Bitbucket Server (aka Stash)
<details>
<summary>Expand</summary>
<ul>
<li>Go to your repo's home page</li>
<li>Click <strong>Settings</strong> in the sidebar</li>
<li>Click <strong>Webhooks</strong> under the <strong>WORKFLOW</strong> section</li>
<li>Click <strong>Create webhook</strong></li>
<li>Enter "Atlantis" for <strong>Name</strong></li>
<li>Set <strong>URL</strong> to your ngrok url with <code>/events</code> at the end. Ex. <code>https://c5004d84.ngrok.io/events</code></li>
<li>Double-check you added <code>/events</code> to the end of your URL.</li>
<li>Set <strong>Secret</strong> to your random string</li>
<li>Under <strong>Repository</strong> select <strong>Push</strong></li>
<li>Under <strong>Pull Request</strong>, select: Opened, Modified, Merged, Declined, Deleted and Comment added</li>
<li>Click <strong>Save</strong><img src="./images/bitbucket-server-webhook.png" alt="Bitbucket Webhook" style="max-height: 500px;"></li>
</ul>
</details>


## Create an access token for Atlantis
We recommend using a dedicated CI user or creating a new user named **@atlantis** that performs all API actions, however for testing,
you can use your own user. Here we'll create the access token that Atlantis uses to comment on the pull request and
set commit statuses.

### GitHub
### GitHub or GitHub Enterprise
- follow [https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token)
- create a token with **repo** scope
- set the token as an environment variable
```
TOKEN="{YOUR_TOKEN}"
```

### GitLab
### GitLab or GitLab Enterprise
- follow [https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token)
- create a token with **api** scope
- set the token as an environment variable
Expand All @@ -132,6 +171,17 @@ TOKEN="{YOUR_TOKEN}"
TOKEN="{YOUR_TOKEN}"
```

### 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 set the token as an environment variable
```
TOKEN="{YOUR_TOKEN}"
```


## Start Atlantis
You're almost ready to start Atlantis, just set two more variables:
Expand All @@ -140,6 +190,9 @@ You're almost ready to start Atlantis, just set two more variables:
USERNAME="{the username of your GitHub, GitLab or Bitbucket user}"
REPO_WHITELIST="$YOUR_GIT_HOST/$YOUR_USERNAME/$YOUR_REPO"
# ex. REPO_WHITELIST="github.com/runatlantis/atlantis"
# If you're using Bitbucket Server, $YOUR_GIT_HOST will be the domain name of your
# server without scheme or port and $YOUR_USERNAME will be the name of the **project** the repo
# is under, **not the key** of the project.
```
Now you can start Atlantis. The exact command differs depending on your Git Host:

Expand Down Expand Up @@ -196,6 +249,18 @@ atlantis server \
--repo-whitelist="$REPO_WHITELIST"
```

### Bitbucket Server (aka Stash)
```bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--bitbucket-webhook-secret="$SECRET" \
--bitbucket-base-url="$BASE_URL" \
--repo-whitelist="$REPO_WHITELIST"
```

## Create a pull request
Create a pull request so you can test Atlantis.
::: tip
Expand Down
Binary file added runatlantis.io/guide/images/bitbucket-server-webhook.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion runatlantis.io/guide/requirements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
* GitHub (public, private or enterprise)
* GitLab (public, private or enterprise)
* Bitbucket Cloud aka bitbucket.org (public or private)
* Bitbucket Server aka Stash (Coming soon: [https://github.com/runatlantis/atlantis/issues/190](https://github.com/runatlantis/atlantis/issues/190))
* Bitbucket Server aka Stash

## Remote State
Atlantis supports all remote state backends. It **does not** support local state
Expand Down

0 comments on commit ddbf967

Please sign in to comment.