Merge pull request #192444 from craigshoemaker/swa/preview-env

[Static Web Apps] Preview environments

Author: hmacgregor1

articles/static-web-apps/TOC.yml

@@ -48,8 +48,14 @@
           href: user-information.md
         - name: Custom authentication
           href: authentication-custom.md
-    - name: Review pull requests in pre-production environments
-      href: review-publish-pull-requests.md
+    - name: Preview environments
+      items:
+        - name: About preview environments
+          href: preview-environments.md
+        - name: Pull request environments
+          href: review-publish-pull-requests.md
+        - name: Branch environments
+          href: branch-environments.md
     - name: Custom domains
       items:
       - name: About custom domains

articles/static-web-apps/branch-environments.md

@@ -0,0 +1,66 @@
+---
+title: Create branch preview environments in Azure Static Web Apps
+description: Expose stable URLs for specific branches to evaluate changes in Azure Static Web Apps
+author: craigshoemaker
+ms.author: cshoe
+ms.service: static-web-apps
+ms.topic: conceptual
+ms.date: 03/29/2022
+ms.custom: template-how-to
+---
+
+# Create branch preview environments in Azure Static Web Apps
+
+You can configure your site to deploy every change made to branches that aren't a production branch. This preview deployment lives for the entire lifetime of the branch and is published at a stable URL that includes the branch name. For example, if the branch is named `dev`, then the environment is available at a location like `<DEFAULT_HOST_NAME>-dev.<LOCATION>.azurestaticapps.net`.
+
+## Configuration
+
+To enable stable URL environments, make the following changes to your [configuration file](configuration.md).
+
+- Set the `production_branch` input on the `static-web-apps-deploy` GitHub action to your production branch name. This ensures changes to your production branch are deployed to the production environment, while changes to other branches are deployed to a preview environment.
+- List the branches you want to deploy to preview environments in the `on > push > branches` array in your workflow configuration so that changes to those branches also trigger the GitHub Actions deployment.
+  - Set this array to `**` if you want to track all branches.
+
+## Example
+
+The following example demonstrates how to enable branch preview environments.
+
+```yml
+name: Azure Static Web Apps CI/CD
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - staging
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    branches:
+      - main
+
+jobs:
+  build_and_deploy_job:
+    ...
+    name: Build and Deploy Job
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: true
+      - name: Build And Deploy
+        id: builddeploy
+        uses: Azure/static-web-apps-deploy@v1
+        with:
+          ...
+          production_branch: "main"
+```
+
+> [!NOTE]
+> The `...` denotes code skipped for clarity.
+
+In this example, the preview environments are defined for the `dev` and `staging` branches. Each branch is deployed to a separate preview environment.
+
+## Next Steps
+
+> [!div class="nextstepaction"]
+> [Review pull requests in pre-production environments](./review-publish-pull-requests.md)

articles/static-web-apps/preview-environments.md

@@ -0,0 +1,35 @@
+---
+title: Preview environments in Azure Static Web Apps
+description: Expose preview environments to evaluate changes in Azure Static Web Apps
+author: craigshoemaker
+ms.author: cshoe
+ms.service: static-web-apps
+ms.topic: conceptual
+ms.date: 03/29/2022
+ms.custom: template-how-to
+---
+
+# Preview environments in Azure Static Web Apps
+
+By default, when you deploy a site to Azure Static Web Apps [each pull request deploys a preview version of your site available through a temporary URL](review-publish-pull-requests.md). This version of the site allows you to review changes before merging pull requests. Once the pull request (PR) is closed, the temporary environment disappears.
+
+Beyond PR-driven temporary environments, you can enable preview environments that feature stable locations. The URLs for preview environments take on the following form:
+
+  ```text
+  <DEFAULT_HOST_NAME>-<BRANCH_OR_ENVIRONMENT_NAME>.<LOCATION>.azurestaticapps.net
+  ```
+
+## Deployment types
+
+The following deployment types are available in Azure Static Web Apps.
+
+- **Production**: Changes to production branches are deployed into the production environment. Your custom domain points to this environment, and content served from this location is indexed by search engines.
+
+- [**Pull requests**](review-publish-pull-requests.md): Pull requests against your production branch deploy to a temporary environment that disappears after the pull request is closed. The URL for this environment includes the PR number as a suffix. For example, if you make your first PR, the preview location looks something like `<DEFAULT_HOST_NAME>-1.<LOCATION>.azurestaticapps.net`.
+
+- [**Branch**](branch-environments.md): You can optionally configure your site to deploy every change made to branches that aren't a production branch. This preview deployment lives for the entire lifetime of the branch and is published at a stable URL that includes the branch name. For example, if the branch is named `dev`, then the environment is available at a location like `<DEFAULT_HOST_NAME>-dev.<LOCATION>.azurestaticapps.net`.
+
+## Next Steps
+
+> [!div class="nextstepaction"]
+> [Review pull requests in pre-production environments](./review-publish-pull-requests.md)

articles/static-web-apps/review-publish-pull-requests.md

@@ -116,4 +116,4 @@ To verify the changes in production,  open your production URL to load the live
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Setup a custom domain](custom-domain.md)
+> [Branch preview environments](branch-environments.md)