AWS CodeStar Connections name change to CodeConnections

**Why?** The AWS CodeStar Connection service [changed its name to AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/rename.html). These changes will need to be made sooner or later. Since they would introduce breaking changes, this PR adds the name change so we can push it as part of the v4.0.0 release. **What?** * Renamed AWS CodeStar Connections to AWS CodeConnections. * Removed the GitHub source provider, as this was superseded by CodeStar Connections back in the day. With the upcoming major release, it would be a good time to sunset that legacy provider. * Added a CHANGELOG.md file, to track the breaking changes we introduce. I added all releases since v3.0.0, so the changes and release notes are readable in forks of ADF as well. * Removed SecretsManager permissions to AWS CodeBuild as these are not in use.
sbkok · Apr 3, 2024 · f94c0f5 · f94c0f5
1 parent 7a4359f
commit f94c0f5
Show file tree

Hide file tree

Showing 18 changed files with 816 additions and 307 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/docs/admin-guide.md b/docs/admin-guide.md
@@ -20,9 +20,8 @@
       - [Bootstrapping Recommendations](#bootstrapping-recommendations)
     - [Pipelines](#pipelines)
       - [Pipeline Parameters](#pipeline-parameters)
-      - [Using CodeStar Connections for Bitbucket, GitHub, or GitHub
-        Enterprise](#using-codestar-connections-for-bitbucket-github-or-github-enterprise)
-      - [Using GitHub with an OAuth token](#using-github-with-an-oauth-token)
+      - [Using AWS CodeConnections for Bitbucket, GitHub, GitHub Enterprise, or
+        GitLab](#using-aws-codeconnections-for-bitbucket-github-github-enterprise-or-gitlab)
       - [Chaining Pipelines](#chaining-pipelines)
   - [Service Control Policies](#service-control-policies)
   - [Tagging Policies](#tagging-policies)
@@ -557,15 +556,15 @@ pipelines:
 
 Here is an example of passing in a parameter to a pipeline to override the
 default branch that is used to trigger the pipeline from, this time using
-a CodeStar Connection to Bitbucket, GitHub, or GitHub Enterprise as a source
-_(No need for `source_account_id`)_.
+an AWS CodeConnections link to Bitbucket, GitHub, or GitHub Enterprise as a
+source _(No need for `source_account_id`)_.
 
 ```yaml
 pipelines:
   - name: vpc  # The GitHub repo would have this name
     default_providers:
       source:
-        provider: codestar
+        provider: codeconnections
         properties:
           branch: dev/feature
           # Optional, name property will be used if repository is not specified
@@ -580,7 +579,7 @@ pipelines:
           # It is recommended to add a Tag like CreatedBy with the user that
           # created it. So it is clear this parameter is not managed by ADF
           # itself.
-          codestar_connection_path: /adf/my_codestar_connection_param
+          code_connection_path: /adf/my_aws_codeconnections_param
     targets:
       - /security  # Shorthand example
 ```
@@ -629,29 +628,29 @@ globally unique we need some way to define which bucket we want to deploy our
 `output.zip` into at a stage level. The way we accomplish this is we can pass
 in `properties` in the form of `key/value` into the stage itself.
 
-#### Using CodeStar Connections for Bitbucket, GitHub, or GitHub Enterprise
+#### Using AWS CodeConnections for Bitbucket, GitHub, GitHub Enterprise, or GitLab
 
 **Please note:** This is the preferred method to setup GitHub as your source
 provider.
 
-**Prerequisite:** To enable CodeStar Connections to be used the following step
+**Prerequisite:** To enable AWS CodeConnections to be used the following step
 is required:
 
 - Rename file `example-global-iam.yml` to `global-iam.yml` in the following
   path `aws-deployment-framework-bootstrap/adf-bootstrap/deployment/` and
-  ensure the CloudFormation resources `CodeStarConnectionPolicy` is no longer
+  ensure the CloudFormation resources `CodeConnectionsPolicy` is no longer
   commented out.
   **Please note:** the use of `deployment` at the end)
 
-**Important note**: `CodeStarConnectionPolicy` IAM policy is a sample.
+**Important note**: `CodeConnectionsPolicy` IAM policy is a sample.
 Please make sure you update this policy and scope it properly for the use cases
 you want to support.
 
-In order for a pipeline to be connected to Bitbucket, GitHub, or GitHub
-Enterprise you will need to setup an CodeStar Connection first.
+In order for a pipeline to be connected to Bitbucket, GitHub, GitHub
+Enterprise, or GitLab you will need to setup AWS CodeConnections first.
 Please follow the [steps as described in the AWS Developer Tools
 documentation](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections.html)
-on how-to setup a new Connection with your code repository.
+on how-to setup a new connection with your code repository.
 
 Once the connection is created you can store the Connection ARN into
 the Deployment Account with AWS Systems Manager Parameter Store.
@@ -672,7 +671,7 @@ pipelines:
   - name: vpc
     default_providers:
       source:
-        provider: github
+        provider: codeconnections
         properties:
           # Optional, name property will be used if repository is not specified
           repository: example-vpc
@@ -688,53 +687,8 @@ pipelines:
           # itself.
           #
           # Example content of the parameter, plain ARN as a simple string:
-          # arn:aws:codestar-connections:eu-west-1:111111111111:connection/11111111-2222-3333-4444-555555555555
-          codestar_connection_path: /adf/my_github_connection_arn_param
-    targets:
-      - /security
-```
-
-#### Using GitHub With An OAuth Token
-
-**Important note:** Before you continue. It is important to understand that
-this method is not advised to be used by CodePipeline. Instead, please follow
-the instructions to setup a CodeStar connection to pull the code from GitHub.
-Please read the [Using CodeStar Connections for Bitbucket, GitHub, or GitHub
-Enterprise section](#using-codestar-connections-for-bitbucket-github-or-github-enterprise).
-
-In order for a pipeline to be connected to GitHub you will need to create a
-Personal Access Token in GitHub that allows its connection to AWS CodePipeline.
-You can read more about creating a Token
-[here](https://docs.aws.amazon.com/codepipeline/latest/userguide/GitHub-rotate-personal-token-CLI.html).
-Once the token has been created you can store that in AWS Secrets Manager on
-the Deployment Account. The Webhook Secret is a value you define and store in
-AWS Secrets Manager with a path of `/adf/my_teams_token`. By Default, ADF only
-has read access access to Secrets with a path that starts with `/adf/`.
-
-Once the values are stored, you can create the Repository in GitHub as per
-normal. Once its created you do not need to do anything else on GitHub's side
-just update your [deployment map](user-guide.md#deployment-map) to use the new
-source type and push to the deployment account. Here is an example of a
-deployment map with a single pipeline from GitHub, in this case the repository
-on GitHub must be named 'vpc'.
-
-```yaml
-pipelines:
-  - name: vpc
-    default_providers:
-      source:
-        provider: github
-        properties:
-          # Optional, name property will be used if repository is not specified
-          repository: example-vpc
-          owner: bundyfx
-          # The path in AWS Secrets Manager that holds the GitHub Oauth token,
-          # ADF only has access to /adf/ prefix in Secrets Manager
-          oauth_token_path: /adf/github_token
-          # The field (key) name of the json object stored in AWS Secrets
-          # Manager that holds the Oauth token.
-          # e.g. {"token": "123"}
-          json_field: token
+          # arn:aws:codeconnections:eu-west-1:111111111111:connection/11111111-2222-3333-4444-555555555555
+          codeconnections_param_path: /adf/my_github_connection_arn_param
     targets:
       - /security
 ```

diff --git a/docs/providers-guide.md b/docs/providers-guide.md
@@ -20,39 +20,37 @@ Providers and Actions.
   - [Source](#source)
     - [CodeCommit](#codecommit)
       - [Properties](#properties)
-    - [GitHub](#github)
-      - [Properties](#properties-1)
     - [S3](#s3)
+      - [Properties](#properties-1)
+    - [CodeConnections](#codeconnections)
       - [Properties](#properties-2)
-    - [CodeStar](#codestar)
-      - [Properties](#properties-3)
   - [Build](#build)
     - [CodeBuild](#codebuild)
-      - [Properties](#properties-4)
+      - [Properties](#properties-3)
     - [Jenkins](#jenkins)
-      - [Properties](#properties-5)
+      - [Properties](#properties-4)
   - [Deploy](#deploy)
     - [Approval](#approval)
-      - [Properties](#properties-6)
+      - [Properties](#properties-5)
     - [CodeBuild](#codebuild-1)
-      - [Properties](#properties-7)
+      - [Properties](#properties-6)
     - [CodeDeploy](#codedeploy)
-      - [Properties](#properties-8)
+      - [Properties](#properties-7)
     - [CloudFormation](#cloudformation)
-      - [Properties](#properties-9)
+      - [Properties](#properties-8)
     - [Lambda](#lambda)
-      - [Properties](#properties-10)
+      - [Properties](#properties-9)
     - [Service Catalog](#service-catalog)
-      - [Properties](#properties-11)
+      - [Properties](#properties-10)
     - [S3](#s3-1)
-      - [Properties](#properties-12)
+      - [Properties](#properties-11)
 
 ## Source
 
 ```yaml
 default_providers:
   source:
-    provider: codecommit|github|s3|codestar
+    provider: codecommit|s3|codeconnections
     properties:
       # All provider specific properties go here.
 ```
@@ -113,44 +111,6 @@ Provider type: `codecommit`.
   - NB: The `CODEBUILD_CLONE_REF` value can only be used by CodeBuild downstream
     actions.
 
-### GitHub
-
-Use GitHub as a source to trigger your pipeline.
-The repository can also be hosted in another account.
-
-Provider type: `github`.
-
-#### Properties
-
-- *repository* - *(String)* defaults to name of the pipeline.
-  - The GitHub repository name. For example, for the ADF repository it would be
-    `aws-deployment-framework`.
-- *branch* - *(String)* default to configured [adfconfig.yml:
-  config/scm/default-scm-branch](./admin-guide.md#adfconfig).
-  - The Branch on the GitHub repository to use to trigger this specific
-    pipeline.
-- *owner* - *(String)* **(required)**
-  - The name of the GitHub user or organization who owns the GitHub repository.
-    For example, for the ADF repository that would be: `awslabs`.
-- *oauth_token_path* - *(String)* **(required)**
-  - The OAuth token path in AWS Secrets Manager on the Deployment Account that
-    holds the GitHub OAuth token used to create the web hook as part of the
-    pipeline. Read the CodePipeline documentation for more [information on
-    configuring GitHub
-    OAuth](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-GitHub.html#action-reference-GitHub-auth).
-- *json_field* - *(String)* **(required)**
-  - The name of the JSON key in the object that is stored in AWS Secrets Manager
-    that holds the OAuth Token.
-- *trigger_on_changes* - *(Boolean)* default: `True`.
-  - Whether CodePipeline should release a change and trigger the pipeline. When
-    set to False, you either need to trigger the pipeline manually, through a
-    schedule, or through the completion of another pipeline.
-  - This **disables the triggering** of changes when **set to False**.
-  - It will not deploy the web hook that GitHub would otherwise use to trigger
-    the pipeline on changes.
-  - **By default**, it will trigger deploy the web hook and trigger on changes
-    using web hook call executed by GitHub.
-
 ### S3
 
 S3 can be used as the source for a pipeline too. **Please note:** you can use
@@ -180,41 +140,41 @@ Provider type: `s3`.
     CodePipeline. Monitoring the S3 object so it can trigger a release when an
     update took place.
 
-### CodeStar
+### CodeConnections
 
-Use CodeStar as a source to trigger your pipeline. The source action retrieves
+Use CodeConnections as a source to trigger your pipeline. The source action retrieves
 code changes when a pipeline is manually executed or when a webhook event is
-sent from the source provider. CodeStar Connections currently supports the
+sent from the source provider. CodeConnections currently supports the
 following third-party repositories:
 
 - Bitbucket
 - GitHub and GitHub Enterprise Cloud
 - GitHub Enterprise Server
+- GitLab
 
-The AWS CodeStar connection needs to already exist and be in the "Available"
-Status. To use the AWS CodeStar Connection with ADF, its arn needs to be stored
+The AWS CodeConnections needs to exist and be in the "Available" Status.
+To use the AWS CodeConnections with ADF, its ARN needs to be stored
 in AWS Systems Manager Parameter Store in the deployment account's main region
 (see details below). Read the CodePipeline documentation for more
 [information on how to setup the connection](https://docs.aws.amazon.com/dtconsole/latest/userguide/getting-started-connections.html).
 
-Provider type: `codestar`.
+Provider type: `codeconnections`.
 
 #### Properties
 
 - *repository* - *(String)* defaults to name of the pipeline.
-  - The CodeStar repository name. For example, for the ADF repository it would
+  - The repository name. For example, for the ADF repository it would
     be `aws-deployment-framework`.
 - *branch* - *(String)* default to configured [adfconfig.yml: config/scm/default-scm-branch](./admin-guide.md#adfconfig).
-  - The Branch on the third-party repository to use to trigger this specific
-    pipeline.
+  - The Branch on the repository to use to trigger this specific pipeline.
 - *owner* - *(String)* **(required)**
   - The name of the third-party user or organization who owns the third-party
     repository. For example, for the ADF repository that would be: `awslabs`.
-- *codestar_connection_path* - *(String)* **(required)**
-  - The CodeStar Connection ARN token path in AWS Systems Manager Parameter
-    Store in the deployment account in the main region that holds the CodeStar
-    Connection ARN that will be used to download the source code and create the
-    web hook as part of the pipeline. Read the CodeStar Connections
+- *codeconnections_param_path* - *(String)* **(required)**
+  - The CodeConnections ARN path in AWS Systems Manager Parameter Store in the
+    deployment account in the main region that holds the CodeConnections
+    resource ARN that will be used to download the source code and create the
+    web hook as part of the pipeline. Read the CodeConnections
     documentation for more
     [information](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections.html).
 - *output_artifact_format* - *(String)* default: `CODE_ZIP`

diff --git a/docs/samples-guide.md b/docs/samples-guide.md
@@ -27,7 +27,7 @@ In this guide, we will deploy a foundational VPC with associated resources along
 with a ECR Repository to hold our shared container images. Once the VPC is in
 place, we can deploy a ECS Cluster that will run our sample NodeJS application.
 
-ADF supports multiple source types *(Github, CodeCommit, S3, CodeStar)* for
+ADF supports multiple source types *(CodeCommit, S3, and CodeConnections)* for
 pipelines, in this example we will use AWS CodeCommit as the source for our
 pipelines.
 

diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -89,18 +89,25 @@ pipelines:
   - name: vpc
     default_providers:
       source:
-        provider: github
+        provider: codeconnections
         properties:
           # Optional, name property will be used if repository is not specified
           repository: my-github-vpc
           # Who owns this Github Repository
-          owner: bundyfx
-          # The path in AWS Secrets Manager that holds the GitHub Oauth token,
-          # ADF only has access to /adf/ prefix in Secrets Manager
-          oauth_token_path: /adf/github_token
-          # The field (key) name of the json object stored in AWS Secrets
-          # Manager that holds the Oauth token
-          json_field: token
+          owner: awslabs
+          # The path in Amazon Systems Manager Parameter Store that holds the
+          # Connections Arn.
+          # Please note, by default ADF only has access to read /adf/
+          # parameters. You need to create this parameter manually
+          # in the deployment region in the deployment account once.
+          #
+          # It is recommended to add a Tag like CreatedBy with the user that
+          # created it. So it is clear this parameter is not managed by ADF
+          # itself.
+          #
+          # Example content of the parameter, plain ARN as a simple string:
+          # arn:aws:codeconnections:eu-west-1:111111111111:connection/11111111-2222-3333-4444-555555555555
+          codeconnections_param_path: /adf/my_github_connection_arn_param
     params:
       notification_endpoint: [email protected]
     targets:
@@ -384,12 +391,11 @@ pipelines:
   - name: my-web-app-pipeline
     default_providers:
       source:
-        provider: github
+        provider: codeconnections
         properties:
           repository: my-web-app
           owner: cool_coder
-          oauth_token_path: /adf/github_token
-          json_field: token
+          codeconnections_param_path: /adf/my_github_connection_arn_param
     targets:
       - path: /banking/testing
         name: web-app-testing