webfactory · Jun 17, 2020 · Jun 17, 2020 · Jun 17, 2020 · Jun 17, 2020 · Sep 15, 2020
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,13 @@
+# create-aws-codedeploy-deployment Action Changelog
+
+## Version v0.5.1
+
+- Update action code to use the AWS JavaScript SDK v3, to make warnings about the upcoming v2 EOL go away
+
+## Version v0.5.0
+
+- Added a second action to remove deployment groups, e. g. after a PR has been closed or merged. In order to serve both actions from a single repository, the actions were moved to subdirectories. Refer to actions as `webfactory/create-aws-codedeploy-deployment/create-deployment@v0.5.0` and `webfactory/create-aws-codedeploy-deployment/delete-deployment-group@v0.5.0` respectively in your workflow's `uses:` clause.
+
+## Previous versions
+
+No dedicated changelog file has been written. Refer to https://github.com/webfactory/create-aws-codedeploy-deployment/releases for release information.
diff --git a/README.md b/README.md
@@ -36,19 +36,19 @@ jobs:
     deploy:
         runs-on: ubuntu-latest
         steps:
-            -   uses: aws-actions/configure-aws-credentials@v1
+            -   uses: aws-actions/configure-aws-credentials@v4
                 with:
                     aws-access-key-id: ${{ secrets.ACCESS_KEY_ID }}
                     aws-secret-access-key: ${{ secrets.SECRET_ACCESS_KEY }}
                     aws-region: eu-central-1
-            -   uses: actions/checkout@v2
+            -   uses: actions/checkout@v4
             -   id: deploy
-                uses: webfactory/create-aws-codedeploy-deployment@v0.1.0
-            -   uses: peter-evans/commit-comment@v1
+                uses: webfactory/create-aws-codedeploy-deployment/create-deployment@v0.5.0
+            -   uses: peter-evans/commit-comment@v2
                 with:
                     token: ${{ secrets.GITHUB_TOKEN }}
                     body: |
-                        @${{ github.actor }} this was deployed as [${{ steps.deploy.outputs.deploymentId }}](https://console.aws.amazon.com/codesuite/codedeploy/deployments/${{ steps.deploy.outputs.deploymentId }}?region=eu-central-1) to group `${{ steps.deploy.outputs.deploymentGroupName }}`.
+                        @${{ github.actor }} this was deployed as [${{ steps.deploy.outputs.deploymentId }}](https://console.aws.amazon.com/codesuite/codedeploy/deployments/${{ steps.deploy.outputs.deploymentId }}?region=eu-central-1) to group `${{ steps.deploy.outputs.deploymentGroupName }}`.
 ```
 
 First, this configures AWS Credentials in the GitHub Action runner. The [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) action is used for that, and credentials are kept in [GitHub Actions Secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets).
@@ -87,9 +87,6 @@ branch_config:
             serviceRoleArn: arn:aws:iam::1234567890:role/CodeDeployStagingRole
             ec2TagFilters:
                 - { Type: KEY_AND_VALUE, Key: hostname, Value: phobos.stage }
-        deploymentConfig:
-            autoRollbackConfiguration:
-                enabled: false
 ```
 
 The purpose of the `branch_config` section is to tell the action how to configure CodeDeploy Deployment Groups and Deployments, based on the
@@ -101,6 +98,8 @@ The first entry makes the action skip the deployment (do nothing at all) when th
 
 Commits on the `master` branch are to be deployed in a Deployment Group called `production`. All other commits will create or update a Deployment Group named `$BRANCH.staging.acme.tld`, where `$BRANCH` will be replaced with a DNS-safe name derived from the current branch. Basically, a branch called `feat/123/new_gimmick` will use `feat-123-new-gimmick` for `$BRANCH`. Since the Deployment Group Name is available in the `$DEPLOYMENT_GROUP_NAME` environment variable inside your CodeDeploy Lifecycle Scripts, you can use that to create "staging" environments with a single, generic configuration statement.
 
+Similar to `$BRANCH`, for workflows triggered by Pull Requests, the string `$PR_NUMBER` will be replaced by the pull request number.  
+
 The `deploymentGroupConfig` and `deploymentConfig` keys in each of the two cases contain configuration that is passed as-is to the 
 [`CreateDeploymentGroup`](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateDeploymentGroup.html) or 
 [`UpdateDeploymentGroup`](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_UpdateDeploymentGroup.html) API calls (for
@@ -112,37 +111,107 @@ The only addition made will be that the `revision` parameter for `CreateDeployme
 
 ## Usage
 
-0. The basic CodeDeploy setup, including the creation of Service Roles, IAM credentials with sufficient permissions and installation of the
- CodeDeploy Agent on your target hosts is outside the scope of this action. Follow [the documentation](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-codedeploy.html).
-1. [Create a CodeDeploy Application](https://docs.aws.amazon.com/codedeploy/latest/userguide/applications-create.html) that corresponds to your
- repository. By default, this action will assume your application is named by the "short" repository name (so, `myapp` for a `myorg/myapp` GitHub
-  repository), but you can also pass the application name as an input to the action.
+0. The basic CodeDeploy setup, including the creation of Service Roles, IAM credentials with sufficient permissions and installation of the CodeDeploy Agent on your target hosts is outside the scope of this action. Follow [the documentation](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-codedeploy.html).
+1. [Create a CodeDeploy Application](https://docs.aws.amazon.com/codedeploy/latest/userguide/applications-create.html) that corresponds to your repository. By default, this action will assume your application is named by the "short" repository name (so, `myapp` for a `myorg/myapp` GitHub repository), but you can also pass the application name as an input to the action.
 2. Connect your CodeDeploy Application with your repository following [these instructions](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployments-create-cli-github.html).
-3. Configure the [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) action in your workflow and
- provide the necessary IAM credentials as secrets. 
-4. Add the `branch_config` section to your `appspec.yml` file to map branches to Deployment Groups and their configuration. In the above example, the  
-`master` and `.*` sub-sections show the minimal configuration required.
-5. Add `uses: webfactory/create-aws-codedeploy-deployment@v0.1.0` as a step to your workflow file. If you want to use the action's outputs, you
- will also need to provide an `id` for the step.
-
+3. Configure the [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) action in your workflow and provide the necessary IAM credentials as secrets. See the section below for the necessary IAM permissions.
+4. Add the `branch_config` section to your `appspec.yml` file to map branches to Deployment Groups and their configuration. In the above example, the  `master` and `.*` sub-sections show the minimal configuration required.
+5. Add `uses: webfactory/create-aws-codedeploy-deployment/create-deployment@v0.5.0` as a step to your workflow file. If you want to use the action's outputs, you will also need to provide an `id` for the step.
+
+### AWS IAM Permissions
+
+The IAM User that is used to run the action requires the following IAM permissions. Note that depending on your policies you might want to specify narrower Resource ARNs, that is, more specifically tailor the permission to one particular repository and/or application.
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "VisualEditor0",
+            "Effect": "Allow",
+            "Action": [
+                "iam:PassRole",
+                "codedeploy:GetDeployment",
+                "codedeploy:GetApplicationRevision",
+                "codedeploy:CreateDeployment",
+                "codedeploy:RegisterApplicationRevision",
+                "codedeploy:GetDeploymentConfig",
+                "codedeploy:GetDeploymentGroup",
+                "codedeploy:UpdateDeploymentGroup",
+                "codedeploy:CreateDeploymentGroup",
+                "codedeploy:DeleteDeploymentGroup"
+            ],
+            "Resource": [
+                "arn:aws:iam::{your_account_id}:role/{your_codedeploy_service_role}",
+                "arn:aws:codedeploy:eu-central-1:{your_account_id}:deploymentconfig:*",
+                "arn:aws:codedeploy:eu-central-1:{your_account_id}:deploymentgroup:*/*",
+                "arn:aws:codedeploy:eu-central-1:{your_account_id}:application:*"
+            ]
+        }
+    ]
+}
+```
+
+## Race Conditions
+
+As of writing, the AWS CodeDeploy API does not accept new deployment requests for an application and deployment group as long as another deployment is still in progress. So, this action will retry a few times and eventually (hopefully) succeed.
+
+There might be situations where several workflow runs are triggered in quick succession - for example, when merging several approved pull requests in a short time. Since your test suites or workflow runs might take a varying amount of time to finish and to reach the deployment phase (_this_ action), you cannot be sure that the triggered deployments will happen in the order you merged the pull requests (to stick with the example). You could not even be sure that the last deployment made was based on the last commit in your repository.
+
+To work around this, this action includes the GitHub Actions "[run id](https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context)" in the `description` field for created deployments. Before creating a new deployment, it will fetch the _last attempted deployment_ from the AWS API and compare its run id with the current run. If the current run has a _lower_ id than the last attempted deployment, the deployment will be aborted.
+
+This workaround should catch a good share of possible out-of-order deployments. There is a slight chance for mishaps, however: If a _newer_ deployment happens to start _after_ we checked the run id and finishes _before_ we commence our own deployment (just a few lines of code later), this might go unnoticed. To really prevent this from happening, ordering deployments probably needs to be supported on the AWS API side, see https://github.com/aws/aws-codedeploy-agent/issues/248.
+
 ## Action Input and Output Parameters
 
 ### Input
 
 * `application`: The name of the CodeDeploy Application to work with. Defaults to the "short" repo name.
+* `skip-sequence-check`: When set to `true`, do not attempt to make sure deployments happen in order. Use this when the workflow count has been reset or changed to a lower value; possible cause is renaming the workflow file.
+* `config-name`: Name used to look up the deployment config in the `branch_config` section of the `appspec.yml` file. Defaults to the current branch name. By using this override, you can force a particular config to be used regardless of the branch name. Or, you can run the action several times within the same job to create multiple (different) deployments from the same branch.
 
 ### Outputs
 
 * `deploymentId`: AWS CodeDeployment Deployment-ID of the deployment created
 * `deploymentGroupName`: AWS CodeDeployment Deployment Group name used
-* `deploymentGroupCreated`: True, if a new deployment group was created. False, if an existing group was updated.
+* `deploymentGroupCreated`: `1`, if a new deployment group was created; `0` if an existing group was updated.
+
+You can use the expression `if: steps.<your-deployment-step>.outputs.deploymentGroupCreated==true` (or `...==false`) on subsequent workflow steps to run actions only if the deployment created a new deployment group (or updated an existing deployment, respectively).
+
+## Cleaning Up
+
+Sooner or later you might want to get rid of the CodeDeploy Deployment Groups created by this action. For example, when you create deployments for pull requests opened in a repo, you might want to delete those once the PR has been closed or merged.
+
+To help you with this, a second action is included in this repo that can delete Deployment Groups, and uses the same rules to derive the group name as described above.
+
+Here is an example workflow that runs for closed pull requests:
+
+```yaml
+# .github/workflows/cleanup-deployment-groups.yml
+on:
+    pull_request:
+        types:
+            - closed
+
+jobs:
+    deployment:
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: aws-actions/configure-aws-credentials@v4
+                with:
+                    aws-access-key-id: ${{ secrets.ACCESS_KEY_ID }}
+                    aws-secret-access-key: ${{ secrets.SECRET_ACCESS_KEY }}
+                    aws-region: eu-central-1
+            -   uses: actions/checkout@v4
+            -   uses: webfactory/create-aws-codedeploy-deployment/delete-deployment-group@v0.5.0
+```
 
 ## Hacking
 
 As a note to my future self, in order to work on this repo:
 
 * Clone it
-* Run `npm install` to fetch dependencies
+* Run `yarn install` to fetch dependencies
 * _hack hack hack_
 * Run `npm run build` to update `dist/*`, which holds the files actually run
 * Read https://help.github.com/en/articles/creating-a-javascript-action if unsure.
@@ -157,4 +226,4 @@ If you're a developer looking for new challenges, we'd like to hear from you! Ot
 - <https://www.webfactory.de>
 - <https://twitter.com/webfactory>
 
-Copyright 2020 webfactory GmbH, Bonn. Code released under [the MIT license](LICENSE).
+Copyright 2020 - 2024 webfactory GmbH, Bonn. Code released under [the MIT license](LICENSE).
diff --git a/action.yml → create-deployment/action.yml b/action.yml → create-deployment/action.yml
@@ -1,8 +1,14 @@
-name: 'webfactory/create-aws-codedeploy-deployment'
+name: 'webfactory/create-aws-codedeploy-deployment/create-deployment'
 description: 'An Action to deploy GitHub repos with AWS CodeDeploy'
 inputs:
     application:
         description: 'AWS CodeDeploy application name; defaults to short repository name'
+    skip-sequence-check:
+        description: 'When set, skip the check making sure no earlier workflow results are deployed'
+        default: false
+    config-name:
+        description: 'Override name to look up branch_config; default is to use the current branch name.'
+        default: ''
 outputs:
     deploymentId:
         description: AWS CodeDeployment Deployment-ID of the deployment created
@@ -11,8 +17,8 @@ outputs:
     deploymentGroupCreated:
         description: True, if a new deployment group was created; false if an already existing group was used.
 runs:
-    using: 'node12'
-    main: 'dist/index.js'
+    using: 'node20'
+    main: '../dist/create-deployment/index.js'
 
 branding:
     icon: cast

diff --git a/delete-deployment-group/action.yml b/delete-deployment-group/action.yml
@@ -0,0 +1,18 @@
+name: 'webfactory/create-aws-codedeploy-deployment/delete-deployment-group'
+description: 'Delete an AWS CodeDeploy deployment group, e. g. after a PR has been closed'
+inputs:
+    application:
+        description: 'AWS CodeDeploy application name; defaults to short repository name'
+    config-name:
+        description: 'Override name to look up branch_config; default is to use the current branch name.'
+        default: ''
+outputs:
+    deploymentGroupName:
+        description: AWS CodeDeployment Deployment Group name used
+runs:
+    using: 'node20'
+    main: '../dist/delete-deployment-group/index.js'
+
+branding:
+    icon: cast
+    color: orange