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. * Fix [Markdown Linter config](https://github.com/DavidAnson/markdownlint/blob/b2305efafb034b1f328845aec9928b5363ffd646/lib/configuration.d.ts) so repeated headings are allowed if they are in different sections.
awslabs · Apr 8, 2024 · 6a327f2 · 6a327f2
1 parent 5d6e5ce
commit 6a327f2
Show file tree

Hide file tree

Showing 19 changed files with 1,100 additions and 328 deletions.
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -2,11 +2,11 @@
     "emphasis-style": {
         "style": "consistent"
     },
-    "no-duplicate-header": {
-        "allow_different_nesting": true
+    "no-duplicate-heading": {
+        "siblings_only": true
     },
     "heading-style": {
-        "style": "consistent"
+        "style": "atx"
     },
     "ul-style": {
         "style": "dash"
@@ -28,7 +28,9 @@
     "ol-prefix": {
         "style": "one_or_ordered"
     },
-    "no-inline-html": true,
+    "no-inline-html": {
+        "allowed_elements": []
+    },
     "no-emphasis-as-heading": {
         "punctuation": ".,;:!。，；:"
     },

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/docs/admin-guide.md b/docs/admin-guide.md
@@ -20,9 +20,9 @@
       - [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, or
+        GitLab](#using-aws-codeconnections-for-bitbucket-github-or-gitlab)
+      - [AWS CodeStar Connection](#aws-codestar-connection)
       - [Chaining Pipelines](#chaining-pipelines)
   - [Service Control Policies](#service-control-policies)
   - [Tagging Policies](#tagging-policies)
@@ -282,7 +282,8 @@ SCPs or CloudFormation templates that ADF will apply.
 The Deployment Account is the gatekeeper for all deployments throughout an
 Organization. Once the baselines have been applied to your accounts via the
 bootstrapping process, the Deployment account connects the dots by taking
-source code and resources from a repository _(e.g. GitHub, CodeCommit or S3)_
+source code and resources from a repository _(e.g. CodeCommit, S3, or external
+via AWS CodeConnections or an AWS CodeStar Connection)_
 and into the numerous target accounts and regions as defined in the deployment
 map files via AWS CodePipeline.
 
@@ -557,15 +558,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 GitLab 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 +581,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,50 +630,63 @@ 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, or GitLab
 
-**Please note:** This is the preferred method to setup GitHub as your source
-provider.
+**Please note:** This is the preferred method to setup external sources.
+If you have configured an AWS CodeStar Connection before and wonder how-to
+set it up again, please read the [AWS CodeStar Connection
+steps](#aws-codestar-connection).
 
-**Prerequisite:** To enable CodeStar Connections to be used the following step
-is required:
+**Prerequisite:** To enable AWS CodeConnections to be used the following steps
+are 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
-  commented out.
-  **Please note:** the use of `deployment` at the end)
+- Navigate to the `aws-deployment-framework-bootstrap` repository, specifically
+  the `/adf-bootstrap/deployment/` folder (notice the `deployment` OU folder at
+  the end).
+- There should be a `global-iam.yml` file in that folder. If not, please rename
+  or copy the `example-global-iam.yml` file to `global-iam.yml` to proceed.
+- Inside the `global-iam.yml` file ensure the CloudFormation resources
+  named `CodeConnectionsPolicy` is no longer commented out.
 
-**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, 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.
 
+Before you proceed, please check the Connection ARN of the connection you
+configured. Depending on the method and creation time of the connection it
+might have created a CodeStar Connection instead. If it did, the ARN will
+include the `codestar` keyword. If so, please proceed with the steps described
+in the [AWS CodeStar Connection](#aws-codestar-connection) first before you
+continue.
+
 Please use the `/adf/` prefix for this parameter. For example:
 `/adf/my_source_connection_param`
 As ADF has read access to parameters that start with `/adf/`.
 
-Once the values are stored, you can create the Repository in GitHub as per
-normal. Once its created you no further steps are required 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'.
+Once the values are stored, you can create the Repository in your external
+source provider (Bitbucket, GitHub, or GitLab) as per normal.
+Once the repository is ready, no further steps are required on the external
+source provider'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 an external source provider, in this
+case the external repository must be named 'vpc'.
 
 ```yaml
 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,56 +702,57 @@ 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
+          # arn:aws:codeconnections:eu-west-1:111111111111:connection/11111111-2222-3333-4444-555555555555
+          codeconnections_param_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 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
-    targets:
-      - /security
-```
+#### AWS CodeStar Connection
+
+**Please note:** Only proceed with the steps in this document if you have an
+existing AWS CodeStar Connection you like to maintain. With the [announcement
+of the AWS CodeStar Connection to AWS CodeConnections name
+change](https://aws.amazon.com/about-aws/whats-new/2024/03/aws-codeconnections-formerly-codestar-connections/)
+the preferred method to link GitHub, GitLab, Bitbucket, and other sources is
+AWS CodeConnections. You do not need to replace the AWS CodeStar Connection
+with an AWS CodeConnections resource if you have one already. According to the
+service documentation it will continue to be supported via the new AWS
+CodeConnections API without requiring further changes in ADF's config or the
+deployment maps.
+
+If you are about to setup a new connection to an external source code provider,
+please consider following the [AWS CodeConnections
+steps](#using-aws-codeconnections-for-bitbucket-github-or-gitlab)
+instead.
+
+**Prerequisite:** To enable an AWS CodeStar Connection to be used the following
+steps are required:
+
+- Navigate to the `aws-deployment-framework-bootstrap` repository, specifically
+  the `/adf-bootstrap/deployment/` folder (notice the `deployment` OU folder at
+  the end).
+- There should be a `global-iam.yml` file in that folder. If not, please rename
+  or copy the `example-global-iam.yml` file to `global-iam.yml` to proceed.
+- Inside the `global-iam.yml` file ensure the CloudFormation resources
+  named `CodeConnectionsPolicy` is no longer commented out.
+- Also make sure the CodeStar actions are no longer commented out.
+
+**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. We recommend that you leave this policy name as
+`CodeConnectionsPolicy`, even though you are setting up a
+`CodeStar Connection`. This will make it easier to detect required updates if
+these would-be introduced by future ADF versions.
+
+The remaining steps are the same as configuring an AWS CodeConnections
+setup. So please follow the next steps as documented in the
+[Using AWS CodeConnections for Bitbucket, GitHub, or GitLab
+section](#using-aws-codeconnections-for-bitbucket-github-or-gitlab).
+
+**Please note: While the AWS CodeConnections source provider name is
+`codeconnections`, if the configured connection ARN refers to an AWS CodeStar
+Connection it will set that up instead.
 
 #### Chaining Pipelines