Production workflows for teams
Since the launch of the AWS Amplify CLI in August, one of the most requested features has been the ability to handle multiple teams & multiple environments.
In the latest release of the AWS Amplify Toolchain, there is now first-class support for handling multiple environments & teams when developing applications with AWS Amplify.
Another big recent launch is the Amplify Console, a continuous delivery and hosting service for mobile web applications. The Amplify Console works hand in hand with the multi-environment features we’re about to go over in this post & we’ll learn how to leverage it when working with multiple Amplify environments in a centralized workflow with a team.
The Amplify Console also has features like continuous deployment, easy custom domains + free HTTPS, multi-environment support with feature branch deploys, & allows you to manage your frontend &serverless backend in a single deployment workflow.
To learn more about the Amplify Console, click here.
Testing it out
Install the Amplify CLI using the following command:
npm install -g @aws-amplify/cli
If this is your first time using the AWS Amplify CLI, check out this video to learn how to configure it after installation.
Using the New Environments Feature
There is now a new command that is available in the CLI, the env command:
When this command is run, you will be given a list of available options for working within your environments:
- sync — Syncs your environment with the current cloud environment. This will allow you to pull down a newer version of the environment in which you are already working
- checkout <envname> — Moves your environment to the environment specified in the command
- list — Displays a list of all the environments in your Amplify project
- get — Displays the details of the environment specified in the command
- add — Adds an already existing Amplify project stack to your local backend
- remove — Removes an environment from the Amplify project
To create a new environment in an existing AWS Amplify project, you can run the
amplify init command & you will now have the option to initialize a new environment in the current working project.
Next, let’s learn how to use multiple environments in two different scenarios:
- Working with multiple local Amplify environments
- Working with multiple Amplify environments using the Amplify Console in a centralized workflow / with a team
Working with multiple local Amplify environments
Let’s first look at how to create & manage multiple local Amplify environments.
In this example, we’ll see how to add & test out new features without affecting our original / main Amplify project. When the new feature is ready, we’ll merge it into our main Amplify environment & delete the feature environment.
The workflow we will use to demonstrate this is:
- Create a new Amplify project. The main Amplify environment will be called dev.
- Add a new feature to the main environment (authentication)
- Push the main Amplify environment to create the authentication service in our AWS account
- Create a new Amplify environment to create & test a new feature. In this new environment, we’ll add and test out an AWS AppSync GraphQL API . This new Amplify environment will be called apifeature.
- Once we test out this new feature & know it works the way we would like, we’ll then merge it into our existing dev environment.
To demonstrate this workflow in a framework-agnostic fashion, we’ll create a new Amplify project in an empty directory & walk through all of the above steps.
Initializing a new Amplify project
mkdir blanktest cd blanktest amplify init
When prompted, give the environment a name of dev & feel free to choose the default for all other choices for the purposes of this demo.
Next, in the new environment, add an authentication service by using the following command:
amplify add auth
When prompted, if you want to use the default authentication and security configuration, choose Yes.
Now, we’ll create the service in our account by running the push command:
- Are you sure you want to continue? Y
Now that we have successfully added the authentication service to our dev environment, let’s look at how to create a new feature-api environment to create & test out the AWS AppSync GraphQL API.
Creating a new Amplify environment
To create the new environment, we’ll use the
amplify env add
- Do you want to use an existing environment? N
- Enter a name for the environment: apifeature
Now, the new environment is created. If we would like to view all current environments, we can run the following command to list them:
amplify env list | Environments | | ------------ | | dev | | *apifeature |
The environment we are currently using should now show up in the list with an asterisk next to it.
Now that we have initialized the new environment, we need to create the application stack in our account so we can begin testing. To do so, run the push command:
Now that we have a new environment created, we’ll add the new feature:
amplify add api
When prompted for the type of API, choose GraphQL & choose the defaults for the rest of the options for the purposes of this demo.
Once the above steps have been completed, we’ll run amplify push to create the GraphQL API in our account:
- Are you sure you want to continue? Y
- Do you want to generate code for your newly created GraphQL API? N
After the service has been successfully created, we can run the status command to see the current status of our project:
amplify status Current Environment: apifeature | Category | Resource name | Operation | Provider plugin | | -------- | ------------- | --------- | ----------------- | | Auth | cognitoauth | No Change | awscloudformation | | Api | blanktest | No Change | awscloudformation |
If we visit the AWS AppSync console, we should now see a new AWS AppSync API appended with apifeature (blanktest-apifeature).
Merging the new feature into the dev environment
Now, how to we get this new functionality into our original dev environment? This is pretty easy. We need to check out the original dev environment & we’ll now see a copy of this feature along with all of its configuration already set up for us.
amplify env checkout dev amplify status Current Environment: dev | Category | Resource name | Operation | Provider plugin | | -------- | ------------- | --------- | ----------------- | | Api | blanktest | Create | awscloudformation | | Auth | cognitoauth | No Change | awscloudformation |
We now see the API category in our project. We also see that the operation corresponding to API is currently Create. This means that the while the configuration for the AppSync API is ready to go, the actual service has not yet been created in our account. To do this, we need to run
Now, the new AppSync GraphQL API has been created & it should now show up in our dashboard.
For a quick demo of this workflow, check out the following video:
Deleting an environment
Now that we’ve successfully merged our feature into our main environment, how do we clean up the resources we created in the test environment? This is easy, we can just run the following command:
amplify env remove apifeature
- Do you also want to remove all the resources of the environment from the cloud? Y
The remove command will delete everything from this environment (IAM roles, Cognito services, AWS AppSync API & DynamoDB table) for you.
Multiple Amplify environments with a team
Now that we know how to manage multiple environments locally, how do we manage multiple environments in a git oriented workflow & with a team?
There are two main ways to work with Amplify projects within a team:
- Team members working on their own sandbox environments (Recommended)
- Team-members sharing the same dev backend to work on
The example we’re going to look at (1) is how a team-member can work on their own sandbox environment and then merge changes to the dev environment to test some changes, & then to master once testing is finished.
To get started, we want to have two separate git branches: master & dev. We’ll also want to have two separate Amplify environments that correspond to those environments.
Setting up master and dev environments
To set up the master & dev environments, we’ll go ahead and initialize them:
$ amplify env add ? Enter a name for the environment master // Provide AWS Profile info // Add amplify categories using `amplify add <category>` $ git init $ git add <all project related files> $ git commit -m <commit-message> $ git remote add origin firstname.lastname@example.org:<repo-name> $ git push origin master
Once we have our ‘master’ branch setup in Git, we’ll set up a ‘dev’ environment in your Amplify project (which would be based on your ‘master’ environment):
$ amplify init ? Do you want to use an existing environment? No ? Enter a name for the environment dev // Provide AWS Profile info
This will set up another environment for the project in the cloud. The backend-configs and resources are now cloned from the ‘master’ environment. Run
amplify push to provision all the AWS resources for your new environment (dev).
Now push the changes to the ‘master’ branch (you would just see changes to the team-provider-info.json file — when running a
git status command. This file has cumulative stack information for all the project environments which are useful when you want to share the same backend within a team). After this, let’s create a new git branch – ‘dev’ corresponding to the new environment we just created.
$ git add . $ git commit -m "creating master amplify environment" $ git push origin master $ git checkout -b dev $ git push origin dev
Sharing a project within a team
Now we have two independent environments (master & dev) in the cloud and have corresponding git branches with our amplify backend infrastructure code on Git.
Suppose a team member wants to work on the same Amplify project, add some features to it and then push changes to the dev environment to test some changes. They would perform the following steps:
$ git clone <git-repo> $ cd <project-dir> $ git checkout -b mysandbox $ amplify init ? Do you want to use an existing environment? No ? Enter a name for the environment mysandbox // Rest of init steps // Add/update any backend configurations using amplify add/update <category> $ amplify push $ git push -u origin mysandbox
Next, suppose the team-member wants to move these changes to dev and master environments/branches:
$ git checkout dev $ amplify init ? Do you want to use an existing environment? true ? Choose the environment you would like to use: ❯ dev master $ git merge mysandbox $ amplify push $ git push -u origin dev
After testing that everything works fine in the dev stage, you could now merge dev to the master git branch:
$ git checkout master $ amplify init ? Do you want to use an existing environment? true ? Choose the environment you would like to use: dev ❯ master $ git merge dev $ amplify push $ git push -u origin master
There are other workflows, including allowing team-members to share the same dev backend & even sharing projects outside the team.
To learn more about these other workflows, check out the documentation listed here.
After the release of the Amplify CLI, one of the most requested features was the ability to create multiple environments & share them with teams, so I’m really excited for this new release.
The AWS Amplify CLI & client library are both open source & we encourage discussion, issues, pull requests & feature requests. If you’re interested in participating in the project, check out the repos here.
To learn more about AWS Amplify, check out the documentation here.
My Name is Nader Dabit . I am a Developer Advocate at AWS Mobile working with projects like AWS AppSync and AWS Amplify, the author of React Native in Action, & the editor of React Native Training & OpenGraphQL.