add docs for ephemeral previews

content/en/user-guide/deployments/ephemeral-previews/index.md

@@ -0,0 +1,97 @@
+---
+title: "Ephemeral Previews"
+linkTitle: "Ephemeral Previews"
+weight: 2
+description: Create an Ephemeral Preview to deploy your application changes to an Ephemeral Instance before merging them to the production branch
+---
+
+## Introduction
+
+Ephemeral Previews allows you to generate an preview environment from GitHub Pull Request (PR) builds. You can use Ephemeral Preview to temporarily deploy your AWS-powered application to a LocalStack Ephemeral Instance and preview your application changes. Currently, the Preview Deployments are only supported for GitHub repositories using GitHub Actions.
+
+## Getting started
+
+This guide is designed for users new to Ephemeral Previews and assumes basic knowledge of GitHub Actions. To get started with a ready-to-use template, you can fork the [`bref-localstack-sample`](https://github.com/localstack-samples/bref-localstack-sample) repository. The sample application deploys a serverless PHP application using Bref and the Serverless Framework.
+
+### Prerequisites
+
+- [LocalStack Account](https://app.localstack.cloud/)
+- [GitHub Account](https://github.com)
+
+### Create the Ephemeral Preview
+
+To create an Ephemeral Preview, you can use the [official LocalStack GitHub Action](https://github.com/localstack/setup-localstack). The sample repository has been configured to use the workflow described above. For your custom repository, create a new file named `ci-pipeline.yml` in the `.github/workflows` directory. This file will contain the CI pipeline that runs on every pull request. This pipeline deploys the application to a LocalStack Ephemeral Instance.
+
+The workflow file to create the Ephemeral Preview looks like this:
+
+```yaml
+name: Create PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Deploy Preview
+        uses: LocalStack/setup-localstack/preview@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          localstack-api-key: ${{ secrets.LOCALSTACK_API_KEY }}
+          preview-cmd: |
+            # Add your custom deployment commands here. 
+            # Below is an example for the Bref Serverless application.
+            export AWS_DEFAULT_REGION=us-east-1
+            npm install --include=dev
+            npm run build
+            composer require bref/bref
+            mv .env.example .env
+            php artisan key:generate
+            npm run serverless -- deploy --stage dev
+
+            pip install awscli-local[ver1]
+            apiId=$(awslocal apigatewayv2 get-apis| jq -r '.Items[0].ApiId')
+            echo "Open URL: $AWS_ENDPOINT_URL/restapis/$apiId/dev/_user_request_/"
+```
+
+You will also need to configure the `LOCALSTACK_API_KEY` as a repository secret. You can find the API key on the [LocalStack Web Application](https://app.localstack.cloud/account/apikeys). The `GITHUB_TOKEN` is automatically created by GitHub and you can use it without any additional configuration.
+
+### Attach the Preview URL
+
+You can now attach the Preview URL to the pull request.  The sample repository has been configured to use the workflow described above. For your custom repository, create a new file named `ci-finalize.yml` in the `.github/workflows` directory. This file contains the CI pipeline that attaches a comment to the pull request with the Preview URL of the deployed application.
+
+The workflow file to create the Ephemeral Preview looks like this:
+
+```yaml
+name: Finalize PR Preview
+
+on:
+  workflow_run:
+    workflows: ["Create PR Preview"]
+    types:
+      - completed
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Finalize PR comment
+        uses: LocalStack/setup-localstack/finish@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          include-preview: true
+```
+
+### Open a Pull Request
+
+Once your changes are in your repository, open a new pull request. GitHub will receive the request and trigger your workflow. You can track the workflow's status and logs in the **Checks** section of the pull request.
+
+After a short delay, the workflow will update the pull request with the URL of your preview environment. Just click on it to see the changes in real-time.
+
+Each time the branch is updated, the same workflow will automatically refresh the preview environment.