Prerequisites

AWS account

• A CDK bootstrapped AWS account: You must bootstrap your AWS CDK environment in the target region you want to deploy, using the AWS CDK toolkit's cdk bootstrap command. From the command line, authenticate into your AWS account, and run cdk bootstrap 'aws://<YOUR ACCOUNT NUMBER>/<REGION>'. For more information, refer to the AWS CDK's How to bootstrap page.

• Production access for Amazon SES: This solution uses Amazon SES for sending email notifications to application pattern’s subscribers. In order to use this feature, ensure that Amazon SES (in your account) is in a production environment, and not in the sandbox environment. For more information, refer to the Moving out of the Amazon SES sandbox page.

• Your AWS account should be part of an AWS Organization: This prerequisite is only applicable for application patterns that are of the CloudFormation type, and needs to be shared across accounts using AWS Service Catalog, as currently, the AWS Service Catalog AppRegistry attribute groups can only be shared to AWS accounts within an organization. This prerequisite does not apply to CDK-based application patterns.

GitHub and GitHub Enterprise account (required only if you use these for your pattern's source code repository)

By default, the solution uses AWS CodeCommit to create pattern repositories.

Note

To configure GitHub or GitHub Enterprise as your pattern’s source code repository instead, deploy the solution using AWS CDK by following the instructions in the solution README.

The solution supports both GitHub Teams and GitHub Enterprise (Enterprise Cloud and Enterprise Server) plans. A complete list of prerequisites related to GitHub/GitHub Enterprise is listed below:

• GitHub Organization: The solution assumes that an organization exists in the GitHub account. The pattern repositories will be created in this organization.

• GitHub Organization Owner Account: The organization owner is the only account that is allowed to create a GitHub App which is required to create an AWS CodeStar connection to GitHub, GitHub Enterprise Cloud or GitHub Enterprise server.

• AWS CodeStar connection to GitHub, GitHub Enterprise Cloud, or GitHub Enterprise server:

  • The solution integrates with GitHub, GitHub Enterprise Cloud or GitHub Enterprise server using AWS CodeStar connection. To create a AWS CodeStar connection to GitHub or GitHub Enterprise Cloud, refer to the Create a connection to GitHub guide. To create a AWS CodeStar connection to GitHub Enterprise Server, refer to the Create a connection to GitHub Enterprise Server guide.

  • As part of creating a AWS CodeStar connection, a GitHub app is installed to establish the connection between AWS and GitHub. Install the GitHub app in the Organization.

  • GitHub app permissions:

    • The GitHub app must have admin permissions granted as read and write. The admin permission for the GitHub app is required because when a new pattern is created by the solution, its code repository is created with master/main branch as protected. When the pattern’s publishing pipeline runs, it upgrades the package versions and tries to push the change directly to the master/main branch. As the master/main branch is protected, only admins have the required permissions to directly push to the protected branches.

    • For GitHub and GitHub Enterprise in the cloud, the GitHub app has read and write admin permissions by default.

      

      AWS Connector for GitHub

    • For GitHub Enterprise Server, you must manually grant the admin permissions to the GitHub app. For more information about how to grant permissions to the GitHub app, refer to the Editing a GitHub App's permissions guide. Ensure that the permissions changes are accepted by the Organization account before you deploy the solution.

      

      GitHub App permissions

• Once the AWS CodeStar connection has been created successfully using the previous step, create an AWS SSM parameter with the name as githubConnectionArn and value as AWS CodeStar connection ARN.

• GitHub personal access token:

  • Create a personal access token from a GitHub account that is a member of the organization. This token is required by the solution to create the pattern’s code repository in the organization and also to initialize it with an initial commit.

  • Token permissions should have repo and delete repo scopes.

    

    OAuth scopes

  • GitHub personal access token to be stored as a secret in a text form in AWS Secrets Manager with the name githubTokenSecretId. It must be encrypted using the AWS managed key for Secrets Manager (aws/secretsmanager).