yinlinchen / amplify-preview-actions

This action deploys your AWS Amplify pull request preview for your public repository

amplify-preview-actions

AWS Amplify Pull-Request Previews currently only supports private GitHub repository. This amplify-preview-actions GitHub action enables the ability to deploy AWS Amplify Pull-Request Previews for your open source and public GitHub repository.

With this amplify-preview-actions GitHub action, you can define your own rule to deploy the Pull-Request branch to the AWS Amplify console app page for a preview. For example, you can setup a rule only a pull request is labeled with Ready for review and is assigned to a reviewer; and clean up the previews after the pull request is merged or closed.

Getting Started

You can include the action in your workflow as actions/amplify-preview-actions@master.

Basic workflow.yml Example

Deploy a PR preview branch to the Amplify console App page (not the Previews page) after a reviewer is assigned.

Place in a .yml file such as this one in your .github/workflows folder. Refer to the documentation on workflow YAML syntax here.

name: 'Amplify PR Preview'
on:
  pull_request_target:
    types: [review_requested]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master

    - name: set branchname env
      id: setenvname
      run: |
        # use GITHUB_HEAD_REF that is set to PR source branch
        echo "##[set-output name=setbranchname;]$(echo ${GITHUB_HEAD_REF})"

    - name: deploy PR preview
      uses: yinlinchen/amplify-preview-actions@master
      with:
        branch_name: ${{ steps.setenvname.outputs.setbranchname }}
        amplify_command: deploy
      env:
        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        AmplifyAppId: ${{ secrets.AMPLIFYAPPID }}
        BackendEnvARN: ${{ secrets.BACKENDENVARN }}
        EnvironmentVariables: 'key1=value,key2=value'
        AWS_REGION: 'us-east-1'

Configuration

The following settings must be passed as environment variables as shown in the example. Sensitive information, especially AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, should be set as encrypted secrets — otherwise, they'll be public to anyone browsing your repository's source code and CI logs.

Key	Value	Suggested Type	Required	Default
AWS_ACCESS_KEY_ID	Your AWS Access Key. More info here.	secret env	Yes	N/A
AWS_SECRET_ACCESS_KEY	Your AWS Secret Access Key. More info here.	secret env	Yes	N/A
AWS_REGION	The region where you created your bucket. Set to us-east-1 by default. Full list of regions here.	env	Yes	us-east-1
AmplifyAppId	The unique ID for an Amplify app. For example, d6a88fjhifqlks	secret env	Yes	N/A
BackendEnvARN	The Amazon Resource Name (ARN) for a backend environment that is part of the Amplify app. If the Amplify App has no backend environment, don't set it.	secret env	No	N/A
EnvironmentVariables	The environment variables for the branch.	env	No	N/A
GITHUB_TOKEN	The GITHUB_TOKEN, should be supplied if a comment with the preview URL is to be posted on the PR. GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow. You can use it directly, see About the GITHUB_TOKEN secret	github env	No	N/A
NewBackendEnvARN	The Amazon Resource Name (ARN) for a backend environment that is part of an Amplify app.	secret env	No	N/A

AWS_SECRET_ACCESS_KEY & AWS_ACCESS_KEY_ID

Click to expand...

To create these, you'll need to go to IAM Console

1. Click on Users > Add User
2. Click Enable Programmatic Access
3. On the next screen click Attach Existing Policies directly > Create Policy
4. Create a policy called AmplifyPreviewURL based on the policy shown here: AWS access keys & IAM Policy
5. Create the user. Copy the AWS_SECRET_ACCESS_KEY and AWS_ACCESS_KEY_ID to

AmplifyAppId

Click to expand...

To get the Amplify App ID, go to the Amplify Console.

1. Navigate to the application and click General
2. Copy the id from the App Arn, it'll look something like de63t2jjt7llc

BackendEnvARN

Click to expand...

Run:

aws amplify list-backend-environments --app-id=[app_id]

Inputs

amplify_command

type: string
values: deploy | delete

deploy

Creates a new branch for an Amplify app using BackendEnvARN or NewBackendEnvARN and deploy your PR to the Amplify console app page (not the Previews page).

delete

Deletes a branch for an Amplify app.

Advanced Examples

Note: All scenarios are assume that the PR is labeled with Ready for review and a reviewer is assigned.

Scenario 1:

• A developer submits a PR for review using the existing backend environment. A new PR review branch is deployed to the Amplify console app page (not the Previews page) Scenario 1

Scenario 2:

• A developer submits a PR for review using a new backend environment. A new PR review branch using a new backend environment is deployed to the Amplify console app page (not the Previews page) Scenario 2

Scenario 3:

• A reviewer finish reviews a PR, approves it, and merges it into the codebase. The PR preview branch is deleted from the Amplify console app page.

or

• A reviewer finish reviews a PR, does not approve it and the developer closes the PR. The PR preview branch is deleted from the Amplify console app page. Scenario 3

Live Demo

• You can see a complete setup with above scenarios in Amplify workshop bookapp demo and .github/workflows

AWS access keys & IAM Policy

• Minimal necessary permissions IAM policy

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Sid": "VisualEditor1",
              "Effect": "Allow",
              "Action": "amplify:StartJob",
              "Resource": "arn:aws:amplify:${Region}:${Account}:apps/{AppId}/branches/*/jobs/*"
          },
          {
              "Sid": "VisualEditor2",
              "Effect": "Allow",
              "Action": [
                  "amplify:DeleteBranch",
                  "amplify:CreateBranch"
              ],
              "Resource": "arn:aws:amplify:${Region}:${Account}:apps/{AppId}/branches/*"
          }
      ]
  }
  

• How do I create an AWS access key?

• Amplify IAM Policy

• Amplify IAM Roles & MFA

License

This project is distributed under the MIT license.

amplify-preview-actions's Issues

How to find BackendEnvARN from AWS Console

Hi @yinlinchen

Can you tell me where I can find the backend ARN. Thanks.

getting `curl: no URL specified!` when running workflow

Describe the bug
Full error is:

curl: no URL specified!
curl: try 'curl --help' or 'curl --manual' for more information

but the actual preview is being created or deleted

Additional context
current workflow

name: Builds a Amplify Preview
on:
  issue_comment:
    types:
      - created

# This allows a subsequently queued workflow run to interrupt previous runs
concurrency:
  group: '${{ github.workflow }}-${{github.event.issue.number}}'
  cancel-in-progress: true

jobs:
  amplify-preview:
    name: "Amplify Preview"
    runs-on: ubuntu-latest
    environment: CI
    if: ${{ github.event.issue.pull_request && github.event.comment.body == 'preview' }}
    steps:
      - name: React to comment
        uses: dkershner6/reaction-action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commentId: ${{ github.event.comment.id }}
          reaction: "rocket"
      - name: Node set up
        uses: actions/setup-node@v3
        with:
          node-version: "16.15.0"
      - name: Find out PR ref
        id: refs
        uses: eficode/resolve-pr-refs@main
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
      - name: Checkout PR
        uses: actions/checkout@v3
        with:
          ref: ${{ steps.refs.outputs.head_ref }}
      - name: Remove existent PR preview
        uses: yinlinchen/amplify-preview-actions@master
        with:
          branch_name: ${{ steps.refs.outputs.head_ref }}
          amplify_command: delete
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AmplifyAppId: ${{ secrets.AMPLIFY_APPID }}
          BackendEnvARN: ${{ secrets.AMPLIFY_BACKEND_ENV_ARN }}
          AWS_REGION: 'eu-west-2'
      - name: Deploy PR preview
        uses: yinlinchen/amplify-preview-actions@master
        with:
          branch_name: ${{ steps.refs.outputs.head_ref }}
          amplify_command: deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AmplifyAppId: ${{ secrets.AMPLIFY_APPID }}
          BackendEnvARN: ${{ secrets.AMPLIFY_BACKEND_ENV_ARN }}
          AWS_REGION: 'eu-west-2'

Adding duplicate comment when deleting a preview

First off, thank you for this! Getting deployment previews on OSS repos is super helpful!

---

Describe the bug
The action adds a comment when deleting a preview.

To Reproduce

name: PR preview cleanup

on:
  pull_request:
    types: [closed]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - id: setenv
        run: echo "::set-output name=BRANCH_NAME::$(echo ${GITHUB_HEAD_REF})"
      - uses: yinlinchen/amplify-preview-actions@master
        with:
          branch_name: ${{ steps.setenv.outputs.BRANCH_NAME }}
          amplify_command: delete
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AmplifyAppId: d1gko6en628vir
          AWS_REGION: us-east-1

Expected behavior
The preview is deleted, no comment is created.

Screenshots
Duplicate comment (the 2nd is result of deletion of a preview):

Desktop (please complete the following information):

• OS: macOS

Additional context

Minimal IAM Permissions

In the README you link to the Amplify IAM Docs which have an example of the needed IAM permissions to do everything with amplify. Basically an Amplify Admin Policy.

I'd like to see what are the minimal necessary permissions to create the Pull Request preview. My initial thinking is it look like:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AmplifyPreviewURL",
            "Effect": "Allow",
            "Action": [
                "amplify:ListApps",
                "amplify:ListBranches",
                "amplify:ListDomainAssociations",
                "amplify:GetApp",
                "amplify:CreateBranch",
                "amplify:DeleteBranch",
                "amplify:UpdateApp",
                "amplify:CreateApp",
            ],
            "Resource": "[ARN of Amplify Deployment]"
        }
    ]
}

Latest master branch doesn't have a tag version

Describe the bug

The latest master branch version does not have an associated tag and therefore when using yinlinchen/[email protected] you don't get the latest version of the codebase.

If possible can you tag and push the latest version of master?

Cutting of branch name to 10 characters

In the readme, I can see that the branch name is cut short to 10 chracters:

        echo "##[set-output name=setbranchname;]$(echo ${GITHUB_HEAD_REF} | cut -c-10)"

Curious to know why this is required. It was giving me issues. If the branch name is greater than 10 characters, amplify is supplied the truncated name, and it then complains that branch does not exist.

Update Branch

I'd like to suggest a new feature, "update" that's triggered when a PR is updated and the branch already exists. Currently this will break the current workflow since it'll try to re-create the branch and break. See

To implement it, it looks like it'd be as simple as adding an if condition here to check if the branch exists. If it does, skip creation and run start-job.

Action fails if branch is already setup on amplify

Sample Run with Error: https://github.com/SimplQ/simplQ-frontend/pull/401/checks?check_run_id=1335345160

I am probably facing this issue because I have configured only deploy and not delete for my repo, but still it will be nice if in the above mentioned scenario where the branch is already connected on amplify, we don't fail but resume at the line where we emitted error.