# Pull requests previews

We use [AWS Amplify](https://docs.amplify.aws/) to build a preview site for the docs every time someone sends a pull request that updates the docs folder.

Once the build completes, the pull request receives a message with a link to preview the docs.

![image](deployment/images/amplify-message.png)

On this page, you will learn how to enable pull request previews in a repository with the toolchain installed.

<a id="preview-installation"></a>

## Installation

1. Download the file [amplify.yml](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/amplify.yml). Once downloaded, place this file into the root directory of your project.
2. Download the file [docs-amplify-enhanced.yml](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/.github/workflows/docs-amplify-enhanced.yml). After downloading, place this file in the .github/workflows directory within your project.
3. Commit and push the changes to your GitHub repository. Make sure to push these changes to the default branch.
   > #### NOTE
   > To complete the installation, we must list the repository in the company’s AWS account. Contact us in Slack (`#scylla-docs` channel) to set this configuration for you.

## Enable previews

Instructions to enable previews on AWS:

### Step 1: Access AWS Amplify

1. In the company’s AWS account, search for **AWS Amplify** in the search console.
   > ![image](deployment/images/amplify-search.png)
2. Do one of the following:
   > * If you are at the AWS Amplify homepage, click on **Get Started** under **AWS Amplify Hosting**.
   >   > ![image](deployment/images/amplify-get-started.png)
   > * Otherwise, click on **New App** > **Host Web App**.
   >   > ![image](deployment/images/amplify-app.png)
3. Select **Import from GitHub**. You might be asked to grant permissions to AWS Amplify in your GitHub account.
   > ![image](deployment/images/amplify-github.png)
4. Choose **Continue**.

### Step 2: Connect a repository

![image](deployment/images/amplify-branch.png)
1. Find the repository you want to enable pull request previews.
2. Set the default branch (e.g. `master`).
3. Check **Connecting to a monorepo?** and pick the folder `docs`.
4. Choose **Next**.

<a id="configure-build-settings"></a>

### Step 3: Configure build settings

1. Under **Build and test settings**, you should see the message “We detected `amplify.yml` in your repository and will use it to deploy your app.”. If it is not the case, review [Installation](#preview-installation).
   > ![image](deployment/images/amplify-build.png)
2. Expand **Advanced settings** and set **Build image** to `python:3.8`:
   > ![image](deployment/images/amplify-image.png)

Choose **Next**. On the **Review** page, choose **Save and deploy**.

### Step 4: Enable pull request previews

1. On the left sidebar, go to **Previews** page and choose **Preview Settings**.
   > ![image](deployment/images/amplify-preview-settings.png)
2. Select the default branch from the list and choose **Manage**.
   > ![image](deployment/images/amplify-preview-manage.png)
3. Turn on pull request previews.
   > ![image](deployment/images/amplify-preview-enable.png)

The next time you submit a pull request for the branch, AWS Amplify will build the docs automatically and share a preview URL as a pull request comment.

<a id="enable-previews-doc-folder-updated"></a>

## Build previews only if the docs folder is updated

To build pull-request previews only if the pull-request edits the docs folder, set the following environment variables on your AWS Amplify application:

```default
AMPLIFY_DIFF_DEPLOY = true
AMPLIFY_DIFF_DEPLOY_ROOT = docs
AMPLIFY_SKIP_BACKEND_BUILD = true
```

Preview:

> ![image](deployment/images/amplify-env.png)

For more information on how to set environment variables, see the [Environment variables](https://docs.aws.amazon.com/amplify/latest/userguide/environment-variables.html#setting-env-vars) section  on AWS Amplify docs.

## Block a user from triggering previews

Code owners and third-party contributors can build pull request previews.
To ban abusive users, see [Blocking a user from your organization](https://docs.github.com/en/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization).

## Limitations

- Previews builds have a 15 min limit. Nevertheless, we recommend you make sure the command `make dirhtml` does not take more than 3 minutes to build on average.
- Even if your repository is private, all the pull requests previews will be publicly available by default.
- AWS deletes previews when the pull request gets merged or closed.