Amplify for Teams — Part 2: GitFlow

Photo by rawpixel on Unsplash

If you read part 1 of this series, you can skip to the GitFlow section. Otherwise start from the beginning!

Recently Amplify Framework and AWS Amplify Console added support for something called “multiple environments”. Multiple environment support gives you the ability to set up the infrastructure and separate environments needed to support your team’s workflow without having to leave the command line, much like how you interact with Git.

Amplify fits into the standard Git workflow where you switch between different branches. Similarly to how you run "git checkout BRANCH_NAME" you will run “amplify env checkout ENVIRONMENT_NAME" — Amplify Docs

Just as you may create a dev branch where all code is merged before you merge it to master, you can do the same thing with Amplify!

Amplify multi-environment workflow example

By taking advantage of multiple environments, you open the door for your teams to have a more productive workflow that provides exactly the right amount of isolation or shared environment structure needed for you and your team or teams to succeed.

Creating an Amplify Multi-Env Project

Before you can create any multi-env projects, you’ll first have to install the Amplify CLI.

npm i -g @aws-amplify/cli
# OR
yarn global add @aws-amplify/cli

After you have the CLI installed, the next step is to create a new project. In this example I’ll be using create-react-app.

npx create-react-app amplify-multi-env && cd amplify-multi-env

Now that you have a project, you need to set up Amplify.

amplify init

When prompted for an environment name, enter “master”

Running `amplify init` in a terminal

Now it’s time to add an amplify category. For this example we’ll use authentication since it will provide a good example of how separate environments work. To add auth run:

amplify add auth

When prompted choose “use default configuration” for authentication settings

Adding auth to amplify in terminal

After adding auth, you need to push those changes to the cloud:

amplify push

Next you will need to provide a sign in/up flow for users. To do this I recommend using the withAuthenticator higher order component provided by theaws-amplify-react npm package.

You’ll also need the aws-amplify package so you can configure Amplify in your project.

npm i aws-amplify aws-amplify-react
# OR
yarn add aws-amplify aws-amplify-react

Update src/App.js to the following:

Updated src/App.js using withAuthenticator higher order component

Run the project and create a new user by going through the auth flow you just added.

Now that you have a working application with authentication, go ahead and commit the project to your version control provider of choice.

This is necessary since you will connect the project to Amplify Console for CI/CD support.

git add .
git commit -m 'initial commit'
git push -u origin master

Now that your project is under version control, it’s time to connect it to Amplify Console. Open the AWS console to the Amplify service and click on “Connect App”. When prompted:

• Pick the source control provider you used for this project.
• Choose your repository
• Choose the master branch
• For deploying Amplify backend, choose master as well
• Create a service role so that Amplify can work on your behalf

Click “Next” and then on the next screen, click “Save and deploy”.

You can verify your app is deployed by clicking on the preview URL provided for your app.

Once your app is successfully provisioned and deployed, it’s time to dive into workflows.

Workflows

Workflows in Amplify behave much like branches do in a git environment. You can create a new environment like creating a new branch, and you can checkout existing environments like you can checkout existing branches in a git based project. An example workflow might look like this:

git checkout dev
git pull
amplify env checkout dev
amplify env pull
...
git checkout staging
git pull
amplify env checkout staging
amplify env pull
...
git checkout master
git pull
amplify env checkout master
amplify env pull

Now that you have an idea of how multiple environments work in Amplify, let’s dig into some popular development workflows.

GitFlow with Amplify Framework

When using GitFlow, team members will work on features using the same back-end infrastructure. In this type of workflow team members would “checkout” the same environment name when running amplify.

However, first you must create your GitFlow environments to be shared. To create a new environment you run amplify init again, but this time instead of choosing an existing environment, you create a new one.

Name this environment “dev”

Creating a new amplify environment in the terminal

You can confirm your environment was created by running amplify status. Doing so should output something like the image below:

Output of amplify status showing auth category with “Create” operation

As you can see, the auth category has yet to be created even though we “amplify pushed” the auth category in the master environment. Go ahead and push the auth category via:

amplify push

then restart the development process for the project. Then try to log in with the user you created in the master environment. You should be greeted with the following:

User does not exist error when trying to sign into app with user created in master environment

As you can see the user isn’t found. This is because that user was created in a different user pool, the one connected to the “master” amplify environment. Next you’ll want to commit these changes to a dev branch so that you can connect your new environment to Amplify Console.

git checkout -b dev
git add .
git commit -m 'add dev environment'
git push -u origin dev

Once that is done go ahead and connect the branch in Amplify Console. To do that open the console and select your project. Then choose connect branch:

Make sure to choose dev for the Amplify backend environment.

Once connected it should show up in the list of connected branches like so:

List of connected branches in Amplify Console

Now when developers want to share changes, they can checkout the dev branch and the dev Amplify environment and add the new feature or fix. Then anyone who needs access to these changes can checkout the dev environment.

Once this is completed, repeat the process, but this time give your new amplify environment and git branch the name “staging”.

Adding Categories to an Environment

Let’s say you wanted to now add an API to your app. You’ll want to work with it locally, maybe let your team work with it as well and test it before merging to staging, and then master and deploying. What would that process look like? The first thing to do would be to add the api category to your app.

amplify add api

You will be prompted with a few options when you run amplify add api, choose the following responses:

• Use GraphQL
• Provide an API name (I used amplifymultienvexample)
• Choose “Cognito User Pool” for authentication (this will be automatically connected to the user pool we created before).
• Choose no for having an annotated schema
• Choose yes to guided schema creation
• Choose “Single object with fields” for template type
• Choose yes to editing the schema now

Now replace the TODO type with the following:

type Todo @model @auth(rules: [{ allow: owner }]) {
  id: ID!
  name: String!
  description: String
}

Add a GraphQL API to project via Amplify CLI

Now that it’s created you need to “push” those changes so that the back-end infrastructure can be created.

amplify push

When you push your schema to the back-end Amplify CLI will prompt you to ask if you would like all of the corresponding GraphQL operations auto-generated for you. Select “yes” and follow the default prompts.

Running “amplify push” to create back-end infra as well as GraphQL operations on client

Next, update src/App.js with the following code that will allow you to add and list your TODOs:

Source code with support for adding and listing TODOs

Go ahead and add a few TODOs to be sure all is working as expected, if all is well your app should be similar to the gif shown below. 👇

Working TODO support in app

Once you’ve confirmed your app is in fact working and you can save TODOs. It’s time to commit these changes to the dev branch.

git add .
git commit -m 'add GraphQL TODO API to app'
git push

Since you have pushed the code changes, Amplify Console will detect changes to the repository and kick off a new build for you. First by making any updates to your backend services if anything has changed, then by building and deploying your frontend. Because we pushed our changes locally and we haven’t changed any Amplify configuration, Amplify Console won’t rebuild your backend.

This means that as long as nothing changes, only your frontend will be rebuilt, speeding up build times.

Once that build is complete, confirm the project is working as expected in your dev environment by clicking on the accompanying URL for the dev version of the app. Then sign in with the dev user you created and confirm you have your TODOs you created locally.

Because Amplify Console is told to use the dev environment, and you have created TODOs in the dev environment, they can be viewed from your local computer or from the deployed version.

Navigating to deployed “dev” environment of project

Merging Environments

Now that you have confirmed your environments are in sync and you’ve successfully added the api category to your project, as well as tested the functionality, it’s time to merge this environment with the master environment so users of the production app can now add TODOs. To merge the environments you follow a git based flow:

git checkout staging
git merge dev
git push

Because Amplify Console is going to rebuild your backend if necessary, there is no need to do an amplify push locally.

To verify everything is working, log into the project from the staging branch deploy preview and you should be able to create TODOs.

Once your build is complete you can then share the preview url or direct your team to your staging environment to test out your changes.

Next, after allowing your team to review and test your work on the staging environment, you can now merge it to master and let Amplify Console deploy your new version.

git checkout master
git merge staging
git push

The code for this example can be found here, and the deployed project can be found here.

If you enjoyed this post I highly recommend checking out some more of the amazing stuff you can do with Amplify and AppSync! You can find a bunch more awesome resources here and here.

Also, if you want to stay up on the latest things I’m writing about or working on, follow me on Twitter!