If you use Amplify and Git branches, you are going to have a bad time
Tags: serverless, aws, amplify
Published: 2022-06-07 11:38:25

## AWS Amplify is...
A combination of tools that aim to assist with development, deployment, and hosting of your serverless application.

AWS Amplify is three things:
1. It's a cloud service that includes consoles, monitoring tools, build and deploy configurations, and so on.
2. It's a CLI tool that allows you to create Amplify environments, modify them, add resources, and manually publish if you so choose.
3. It's a library for frontend development that simplifies using the resources in your environment like authentication, HTTP calls to your gateways, and more.

You don't have to use the CLI or the library, but you would probably want to since it saves a lot of headaches.

## Deploying applications with Amplify
When you create an Amplify app (which contains different environments under it), you can connect it to a branch in your repository. That creates a `Hosting Environment`. Every hosting environment can be connected to a specific `Backend Environment`. 
When connected to a branch, Amplify will be notified whenever a code was pushed to that branch. At that point, Amplify will rebuild the frontend code in the branch and deploy it.
If connected to a backend environment, Amplify will also redeploy the backend, based on the contents of the branch.

## Amplify CLI tries to follow how Git works
After you created a backend environment `dev` and deployed it, Amplify considers it as the equivalent of Git `remote`. When you want to work on it, you must `pull` that environment to your local machine. You can then change it and `push` your changes back to `remote`.

When you `pull` an environment with Amplify CLI, it does two things:
1. Downloads the content of the environment. The code of the lambdas, the paths defined in the gateway, the templates of the resources, etc.
2. Creates/modifies files that say "what is the current environment in this machine". Similarly to Git, where you can `checkout` multiple branches and your local Git will know which branch you are currently using. For example, a file called `aws-exports.js` that contains a JSON with a lot of configurations. When your application loads, you need to pass the content of that JSON to the AWS Amplify library so it will know what endpoint to contact when your code performs a HTTP call.

When you `push` an environment, Amplify CLI will first check against the `remote` to see if there is any local modifications. If there are, it will compile a .zip with all the files required and upload it to the one currently configured.

## That's a lot of information. I thought Amplify was supposed to make my life simpler...
Tools that make your life easier usually do it by abstracting a lot of knowledge and technical understanding. Your Nespresso machine doesn't even show you the coffee grinds. You just put this aluminum pocket into the hole, push the button, and viola!

Amplify definitely will make your life easier. But this will come with a price, and when something breaks, you must understand what it does in order to fix the problem or preemptively avoid the pitfalls.

## The reason Git and Amplify don't play well together
Imagine the following scenario:
You have a `main` Git branch and you have your `mainBE` backend environment that currently has a lambda function `foo`.

To develop a new backend service, you branch out of `main` to a feature branch called `feat`.

```
> git checkout main
> git checkout -b feat
```
You also clone `mainBE` to a new 
environment: `featBE`

```
> amplify env checkout mainBE
> amplify add env featBE
> amplify push --y
```

This action changes `team-provider-info.json` by introducing a new key to the object: `featBE`. The value currently (almost) equals that of `mainBE`. It will now look like this:
```
"mainBE": {
    "awscloudformation": {
      [...]
      "Region": "us-east-1",
      "AmplifyAppId": "someRandomId"
    },
    "categories": {
      "function": {
        "foo": {
          [...]
          "envVarName": "environment variable value"
        },
    }
},
"featBE": {
    "awscloudformation": {
      [...]
      "Region": "us-east-1",
      "AmplifyAppId": "someRandomId"
    },
    "categories": {
      "function": {
        "foo": {
          [...]
          "envVarName": "environment variable value"
        },
        "bar": {
          [...]
        },
    }
}
        
```

You then add the new lambda called `bar` and push it to your feature environment. 

```
> amplify add function
> amplify push
```

Now the two entries are different. featBE has details of a new lambda, while mainBE does not.

You develop the new service, test it locally and deployed, and everything is done. You then merge your feature branch back into the main branch.
Problem is, any CI/CD process that tries to deploy the backend will fail. The content of `team-provider-info.json` under the `mainBE` key has no definition for the `bar` lambda.

To successfully deploy `mainBE` with the new service, you will need to pull `featBE`, switch to `mainBE`, and push to it. 

```
> amplify env checkout featBE
> amplify pull --y // to overwrite the current content, assuming this is done on a different machine
> amplify env checkout mainBE
> amplify push
```

Amplify will see the new content and update `mainBE`.
But, like before, this will update `team-provider-info.json`, which means your backend environment doesn't match the code in your source control.

You'll need to push this new difference into your git `main` branch. This might sound somewhat reasonable, but if your setup uses the Git flow of having `dev`, `testing`, and `production` branches (and maybe more), you'll find that this cycle of having to merge branches, merge backends, then merge again will grow exponentially with every branch in your flow.

For example: let's assume we already performed all the above mentioned, but we also have staging and production environments.

First, we need to merge the new feature to staging:
```
> git checkout staging
> git merge main
```
At this point, stagingBE won't build. We need to fix this by taking the backend definition in mainBE and applying them to stagingBE
```
> amplify env checkout mainBE
> amplify pull --y
> amplify env checkout stagingBE
> amplify push
```
Now our local branch is ahead of main (and staging)
```
> git checkout main
> git commit -m "Updated Amplify setup of stagingBE"
> git push
```
main is updated, but now main and staging are not aligned
```
> git checkout staging
> git merge main
```
stagingBE should be ok now, but to make sure that the deployed backend matches 100% to the source code, we will redeploy
```
> amplify push --y
```
Now staging environment is ok, but we still have production to deal with
```
> git checkout production
> git merge staging
> amplify env checkout stagingBE
> amplify pull --y
> amplify env checkout productionBE
> amplify push --y
> git checkout main
> git commit -m "Update Amplify setup of productionBE"
> git push
> git checkout staging
> git merge main
> git checkout production
> git merge staging
> amplify push --y
```
_This is the abbreviated version as most Amplify CLI commands require more information either manually entered or via headless mode._

This whole process can take at best ~15 minutes because Amplify takes time to pull and push. At worst, your CI/CD: tests, automation, deployments, etc will need to execute between after each git push in this process, which will take much much longer.

In the end, no matter what you do, you will end up in a situation where the deployed backend is not based on your source code, which is not a situation you want to be in, certainly not on a regular basis.

By the way, the CI/CD built into the Amplify console won't do all of this. It just takes whatever there is in your source code and tries to deploy.

## Finale
All in all, Amplify is a pretty powerful tool but seems to support a common, basic use case. If you need anything more than this, you're probably better off using other tools.