# Feature branch deployments and team workflows
Amplify Hosting is designed to work with feature branch and GitFlow workflows. Amplify uses Git branches to create a new deployment each time you connect a new branch in your repository. After you connect your first branch, you create additional feature branches.
**To add a branch to an app**
1. Choose the app you want to add a branch to.
1. Choose **App settings**, then **Branch settings**.
1. On the **Branch settings** page, choose **Add branch**.
1. Select a branch from your repository.
1. Choose **Add branch.**
1. Redeploy your app.
After you add a branch, your app has two deployments available at the Amplify default domains, such as *https://main.appid.amplifyapp.com* and *https://dev.appid.amplifyapp.com*. This may vary from team-to-team, but typically the **main branch** tracks release code and is your production branch. The **develop branch** is used as an integration branch to test new features. This enables beta testers to test unreleased features on the develop branch deployment, without affecting any of the production end users on the main branch deployment.
**Topics**
+ [
# Team workflows with fullstack Amplify Gen 2 apps
](team-workflows-gen2.md)
+ [
# Team workflows with fullstack Amplify Gen 1 apps
](team-workflows-with-amplify-cli-backend-environments.md)
+ [
# Pattern-based feature branch deployments
](pattern-based-feature-branch-deployments.md)
+ [
# Automatic build-time generation of Amplify config (Gen 1 apps only)
](amplify-config-autogeneration.md)
+ [
# Conditional backend builds (Gen 1 apps only)
](conditional-backends.md)
+ [
# Use Amplify backends across apps (Gen 1 apps only)
](reuse-backends.md)
# Team workflows with fullstack Amplify Gen 2 apps
AWS Amplify Gen 2 introduces a TypeScript-based, code-first developer experience for defining backends. To learn about fullstack workflows with Amplify Gen 2 applications, see [Fullstack workflows](https://docs.amplify.aws/nextjs/deploy-and-host/fullstack-branching/) in the *Amplify docs*.
# Team workflows with fullstack Amplify Gen 1 apps
A feature branch deployment consists of a **frontend**, and an optional **backend** environment. The frontend is built and deployed to a global content delivery network (CDN), while the backend is deployed by Amplify Studio or the Amplify CLI to AWS. To learn how to set up this deployment scenario, see [Building a backend for an application](deploy-backend.md).
Amplify Hosting continuously deploys backend resources such as GraphQL APIs and Lambda functions with your feature branch deployments. You can use the following branching models to deploy your backend and frontend with Amplify Hosting.
## Feature branch workflow
+ Create **prod**, **test**, and **dev** backend environments with Amplify Studio or the Amplify CLI.
+ Map the **prod** backend to the **main** branch.
+ Map the **test** backend to the **develop** branch.
+ Team members can use the **dev** backend environment for testing individual **feature** branches.
![\[A diagram that shows how to map relationships from backend environments to frontend branches.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/FeatureBranchWorkflow.png)
1. Install the Amplify CLI to initialize a new Amplify project.
```
npm install -g @aws-amplify/cli
```
1. Initialize a *prod* backend environment for your project. If you don’t have a project, create one using bootstrap tools like create-react-app or Gatsby.
```
create-react-app next-unicorn
cd next-unicorn
amplify init
? Do you want to use an existing environment? (Y/n): n
? Enter a name for the environment: prod
...
amplify push
```
1. Add *test* and *dev* backend environments.
```
amplify env add
? Do you want to use an existing environment? (Y/n): n
? Enter a name for the environment: test
...
amplify push
amplify env add
? Do you want to use an existing environment? (Y/n): n
? Enter a name for the environment: dev
...
amplify push
```
1. Push code to a Git repository of your choice (in this example we’ll assume you pushed to main).
```
git commit -am 'Added dev, test, and prod environments'
git push origin main
```
1. Visit Amplify in the AWS Management Console to see your current backend environment. Navigate a level up from the breadcrumb to view a list of all backend environments created in the **Backend environments** tab.
![\[The Amplify console showing the backend environments associated with an Amplify app.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/reuse-backend-5.png)
1. Switch to the **Frontend environments** tab and connect your repository provider and *main* branch.
1. On the build settings page, select an existing backend environment to set up continuous deployment with the main branch. Choose *prod* from the list and grant the service role to Amplify. Choose **Save and deploy**. After the build completes you will get a main branch deployment available at *https://main.appid.amplifyapp.com*.
![\[The Configure build settings page with a list of existing backends.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/reuse-backend-2.png)
1. Connect *develop* branch in Amplify (assume *develop* and *main* branch are the same at this point). Choose the *test* backend environment.
![\[The Add repository branch page with a branch and backend environment selected.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/reuse-backend-4.png)
1. Amplify is now set up. You can start working on new features in a feature branch. Add backend functionality by using the *dev* backend environment from your local workstation.
```
git checkout -b newinternet
amplify env checkout dev
amplify add api
...
amplify push
```
1. After you finish working on the feature, commit your code, create a pull request to review internally.
```
git commit -am 'Decentralized internet v0.1'
git push origin newinternet
```
1. To preview what the changes will look like, go to the Amplify console and connect your feature branch. Note: If you have the AWS CLI installed on your system (Not the Amplify CLI), you can connect a branch directly from your terminal. You can find your appid by going to App settings > General > AppARN: *arn:aws:amplify:::apps/*
```
aws amplify create-branch --app-id --branch-name
aws amplify start-job --app-id --branch-name --job-type RELEASE
```
1. Your feature will be accessible at *https://newinternet.appid.amplifyapp.com* to share with your teammates. If everything looks good merge the PR to the develop branch.
```
git checkout develop
git merge newinternet
git push
```
1. This will kickoff a build that will update the backend as well as the frontend in Amplify with a branch deployment at *https://dev.appid.amplifyapp.com*. You can share this link with internal stakeholders so they can review the new feature.
1. Delete your feature branch from Git, Amplify, and remove the backend environment from the cloud (you can always spin up a new one based on by running ‘amplify env checkout prod’ and running ‘amplify env add’).
```
git push origin --delete newinternet
aws amplify delete-branch --app-id --branch-name
amplify env remove dev
```
## GitFlow workflow
GitFlow uses two branches to record the history of the project. The *main* branch tracks release code only, and the *develop* branch is used as an integration branch for new features. GitFlow simplifies parallel development by isolating new development from completed work. New development (such as features and non-emergency bug fixes) is done in *feature* branches. When the developer is satisfied that the code is ready for release, the *feature* branch is merged back into the integration *develop* branch. The only commits to the main branch are merges from *release* branches and *hotfix* branches (to fix emergency bugs).
The diagram below shows a recommended setup with GitFlow. You can follow the same process as described in the feature branch workflow section above.
![\[A diagram that shows a recommended setup with GitFlow.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/GitflowWorkflow.png)
## Per-developer sandbox
+ Each developer in a team creates a sandbox environment in the cloud that is separate from their local computer. This allows developers to work in isolation from each other without overwriting other team members’ changes.
+ Each branch in Amplify has its own backend. This ensures that the Amplify uses the Git repository as a single source of truth from which to deploy changes, rather than relying on developers on the team to manually push their backend or front end to production from their local computers.
![\[A diagram that shows a per developer sandbox workflow.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/AmplifySandboxWorkflow.png)
1. Install the Amplify CLI to initialize a new Amplify project.
```
npm install -g @aws-amplify/cli
```
1. Initialize a *mary* backend environment for your project. If you don’t have a project, create one using bootstrap tools like create-react-app or Gatsby.
```
cd next-unicorn
amplify init
? Do you want to use an existing environment? (Y/n): n
? Enter a name for the environment: mary
...
amplify push
```
1. Push code to a Git repository of your choice (in this example we’ll assume you pushed to main.
```
git commit -am 'Added mary sandbox'
git push origin main
```
1. Connect your repo > *main* to Amplify.
1. The Amplify console will detect backend environments created by the Amplify CLI. Choose *Create new environment* from the dropdown and grant the service role to Amplify. Choose **Save and deploy**. After the build completes you will get a main branch deployment available at *https://main.appid.amplifyapp.com* with a new backend environment that is linked to the branch.
1. Connect *develop* branch in Amplify (assume *develop* and *main* branch are the same at this point) and choose *Create*
# Pattern-based feature branch deployments
Pattern-based branch deployments allow you to automatically deploy branches that match a specific pattern to Amplify. Product teams using feature branch or GitFlow workflows for their releases, can now define patterns such as **release\$1\$1** to automatically deploy Git branches that begin with ‘release’ to a shareable URL.
1. Choose **App settings**, then **Branch settings**.
1. On the **Branch settings** page, choose **Edit**.
1. Select **Branch autodetection** to automatically connect branches to Amplify that match a pattern set.
1. In the **Branch autodetection - patterns** box, enter the patterns for automatically deploying branches.
+ **\$1** – Deploys all branches in your repository.
+ **release\$1** – Deploys all branches that begin with the word ‘release'.
+ **release\$1/** – Deploys all branches that match a ‘release /’ pattern.
+ Specify multiple patterns in a comma-separated list. For example, **release\$1, feature\$1**.
1. Set up automatic password protection for all branches that are automatically created by selecting **Branch autodetection access control** .
1. For Gen 1 applications built with an Amplify backend, you can choose to create a new environment for every connected branch, or point all branches to an existing backend.
1. Choose **Save**.
## Pattern-based feature branch deployments for an app connected to a custom domain
You can use pattern-based feature branch deployments for an app connected to an Amazon Route 53 custom domain.
+ For instructions on setting up pattern-based feature branch deployments, see [Setting up automatic subdomains for an Amazon Route 53 custom domain](to-set-up-automatic-subdomains-for-a-Route-53-custom-domain.md)
+ For instructions on connecting an Amplify app to a custom domain managed in Route 53, see [Adding a custom domain managed by Amazon Route 53](to-add-a-custom-domain-managed-by-amazon-route-53.md)
+ For more information about using Route 53, see [What is Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html).
# Automatic build-time generation of Amplify config (Gen 1 apps only)
**Note**
The information in this section is for Gen 1 apps only. If you want to automatically deploy infrastructure and application code changes from feature branches for a Gen 2 app, see [Fullstack branch deployments](https://docs.amplify.aws/nextjs/deploy-and-host/fullstack-branching/branch-deployments/) in the *Amplify docs*
Amplify supports the automatic build-time generation of the Amplify config `aws-exports.js` file for Gen 1 apps. By turning off full stack CI/CD deployments, you enable your app to autogenerate the `aws-exports.js` file and ensure that updates are not made to your backend at build-time.
**To autogenerate `aws-exports.js` at build-time**
1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/).
1. Choose the app to edit.
1. Choose the **Hosting environments** tab.
1. Locate the branch to edit and choose **Edit**.
![\[The location of the Edit link for a branch in the Amplify console.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/amplify_edit_backend_alternate.png)
1. On the **Edit target backend** page, uncheck **Enable full-stack continuous deployments (CI/CD)** to turn off full-stack CI/CD for this backend.
![\[The location of the checkbox to turn off CI/CD in the Amplify console.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/amplify_turnoff_CICD.png)
1. Select an existing service role to give Amplify the permissions it requires to make changes to your app backend. If you need to create a service role, choose **Create new role**. For more information about creating a service role, see [Adding a service role with permissions to deploy backend resources](amplify-service-role.md).
1. Choose **Save**. Amplify applies these changes the next time you build the app.
# Conditional backend builds (Gen 1 apps only)
**Note**
The information in this section is for Gen 1 apps only. Amplify Gen 2 introduces a TypeScript-based, code-first developer experience. Therefore, this feature isn't necessary for Gen 2 backends.
Amplify supports conditional backend builds on all branches in a Gen 1 app. To configure conditional backend builds, set the `AMPLIFY_DIFF_BACKEND` environment variable to `true`. Enabling conditional backend builds will help speed up builds where changes are made only to the frontend.
When you enable diff based backend builds, at the start of each build, Amplify attempts to run a diff on the `amplify` folder in your repository. If Amplify doesn't find any differences, it skips the backend build step, and doesn't update your backend resources. If your project doesn't have an `amplify` folder in your repository, Amplify ignores the value of the `AMPLIFY_DIFF_BACKEND` environment variable. For instructions on setting the `AMPLIFY_DIFF_BACKEND` environment variable, see [Configuring diff based backend builds for a Gen 1 app](edit-build-settings.md#enable-diff-backend).
If you currently have custom commands specified in the build settings of your backend phase, conditional backend builds won't work. If you want those custom commands to run, you must move them to the frontend phase of your build settings in your app's `amplify.yml` file. For more information about updating the `amplify.yml` file, see [Build specification reference](yml-specification-syntax.md).
# Use Amplify backends across apps (Gen 1 apps only)
**Note**
The information in this section is for Gen 1 apps only. If you want to share backend resources for a Gen 2 app, see [Share resources across branches](https://docs.amplify.aws/nextjs/deploy-and-host/fullstack-branching/share-resources/) in the *Amplify docs*
Amplify enables you to reuse existing backend environments across all of your Gen 1 apps in a given region. You can do this when you create a new app, connect a new branch to an existing app, or update an existing frontend to point to a different backend environment.
## Reuse backends when creating a new app
**To reuse a backend when creating a new Amplify app**
1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/).
1. To create a new backend to use for this example, do the following:
1. In the navigation pane, choose **All apps**.
1. Choose **New app**, **Build an app**.
1. Enter a name for your app, such as **Example-Amplify-App**.
1. Choose **Confirm deployment**.
1. To connect a frontend to your new backend, choose the **Hosting environments** tab.
1. Choose your git provider, and then choose **Connect branch**.
1. On the **Add repository branch** page, for **Recently updated repositories**, choose your repository name. For **Branch**, select the branch from your repository to connect.
1. On the **Build settings**, page do the following:
1. For **App name**, select the app to use for adding a backend environment. You can choose the current app or any other app in the current region.
1. For **Environment**, select the name of the backend environment to add. You can use an existing environment or create a new one.
1. By default, full-stack CI/CD is turned off. Turning off full-stack CI/CD causes the app to run in *pull only* mode. At build time, Amplify will automatically generate the `aws-exports.js` file only, without modifying your backend environment.
1. Select an existing service role to give Amplify the permissions it requires to make changes to your app backend. If you need to create a service role, choose **Create new role**. For more information about creating a service role, see [Adding a service role with permissions to deploy backend resources](amplify-service-role.md).
1. Choose **Next**.
1. Choose **Save and deploy**.
## Reuse backends when connecting a branch to an existing app
**To reuse a backend when connecting a branch to an existing Amplify app**
1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/).
1. Choose the app to connect a new branch to.
1. In the navigation pane, choose **App Settings**, **General**.
1. In the **Branches** section, choose **Connect a branch**.
1. On the **Add repository branch** page, for **Branch**, select the branch from your repository to connect.
1. For **App name**, select the app to use for adding a backend environment. You can choose the current app or any other app in the current region.
1. For **Environment**, select the name of the backend environment to add. You can use an existing environment or create a new one.
1. If you need to set up a service role to give Amplify the permissions it requires to make changes to your app backend, the console prompts you to perform this task. For more information about creating a service role, see [Adding a service role with permissions to deploy backend resources](amplify-service-role.md).
1. By default, full-stack CI/CD is turned off. Turning off full-stack CI/CD causes the app to run in *pull only* mode. At build time, Amplify will automatically generate the `aws-exports.js` file only, without modifying your backend environment.
1. Choose **Next**.
1. Choose **Save and deploy**.
## Edit an existing frontend to point to a different backend
**To edit a frontend Amplify app to point to a different backend**
1. Sign in to the AWS Management Console and open the [Amplify console](https://console.aws.amazon.com/amplify/).
1. Choose the app to edit the backend for.
1. Choose the **Hosting environments** tab.
1. Locate the branch to edit and choose **Edit**.
![\[The location of the Edit link for a branch in the Amplify console.\]](http://docs.aws.amazon.com/amplify/latest/userguide/images/amplify_edit_backend.png)
1. On the **Select a backend environment to use with this branch** page, for **App name**, select the frontend app that you want to edit the backend environment for. You can choose the current app or any other app in the current region.
1. For **Backend environment**, select the name of the backend environment to add.
1. By default, full-stack CI/CD is enabled. Uncheck this option to turn off full-stack CI/CD for this backend. Turning off full-stack CI/CD causes the app to run in *pull only* mode. At build time, Amplify will automatically generate the `aws-exports.js` file only, without modifying the backend environment.
1. Choose **Save**. Amplify applies these changes the next time you build the app.