This serverless app sets up an AWS CodePipeline pipeline as a Continuous Deployment (CD) solution for a SAM project hosted on GitHub or AWS CodeCommit. Once setup, every time you push to the specified Git repository branch, the change will flow through the AWS CodePipeline pipeline.
When this application is deployed, it will create an AWS CodePipeline pipeline that has up to the following 5 stages:
- Source: This stage is the entry point of the pipeline. It is triggered when you push a change to the specified Git repository branch.
- Build: This stage builds the project using AWS CodeBuild.
- Test (optional): This stage runs the integration tests of the project using CodeBuild. This stage will only be created if you provide the
IntegTestRoleNameparameter when setting up this module. See the "Parameters" section below. - Deploy (optional): This stage deploys the project using CloudFormation. This stage will only be created if you provide the
DeployRoleNameparameter when setting up this application. See the "Parameters" section below. - Publish (optional): This stage publishes the project to AWS Serverless Application Repository using the publish app. This stage will only be created if you pass 'true' to the
PublishToSARparameter when setting up this module. See the "Parameters" section below.
Here is an example CodePipeline pipeline that has all 5 stages:
- Create an AWS account if you do not already have one and login
- If your source code repository is on GitHub, then create a GitHub OAuth token (see instructions below).
- Go to this app's page on the Serverless Application Repository and click "Deploy"
- Provide the required app parameters and click "Deploy"
General instructions for creating a GitHub OAuth token can be found here. When you get to the scopes/permissions page, you should select the "repo" and "admin:repo_hook" scopes, which will automatically select all permissions under those two scopes.
The app has the following parameters:
| Parameter | Required | Description |
|---|---|---|
| SourceCodeProvider | Optional | Whether the Git repository is hosted on GitHub or CodeCommit. Allowed values: GitHub, CodeCommit. Default: GitHub |
| ComputeType | Optional | AWS CodeBuild project compute type. See the documentation for details. Default: BUILD_GENERAL1_SMALL |
| EnvironmentType | Optional | Environment type used by AWS CodeBuild. See the documentation for details. Default: LINUX_CONTAINER |
| BuildSpecFilePath | Optional | CodeBuild build spec file name for build stage. See Build Specification Reference for CodeBuild. Default: buildspec.yaml |
| IntegTestRoleName | Optional | IAM role name for test stage. This role needs to be configured to allow codebuild.amazonaws.com and cloudformation.amazonaws.com to assume it. Test stage will not be added if default value is used. Default: '' |
| IntegTestBuildSpecFilePath | Optional | CodeBuild build spec file name for test stage. This parameter is only used if you provide the IntegTestRoleName parameter. See the documentation. Default: integ-test-buildspec.yaml |
| DeployRoleName | Optional | IAM role name for deploy stage. This role needs to be configured to allow cloudformation.amazonaws.com to assume it. Deploy stage will not be added if default value is used. Default: '' |
| DeployStackName | Optional | CloudFormation stack name for deploy stage. Default: ''. This parameter is only used if you provide the DeployRoleName parameter. Note that if you provide the DeployRoleName but do not provide a DeployStackName then AWS CodePipeline will fail. |
| DeployParameterOverrides | Optional | CloudFormation parameter overrides for deploy stage in JSON string. For more information and an example, see the ParameterOverrides parameter of AWS CloudFormation Configuration Properties Reference. Default: {} |
| PublishToSAR | Optional | Boolean to indicate whether or not include publish stage. Allowed values: true, false. Default: false |
The following parameters are only applicable if SourceCodeProvider is GitHub.
| Parameter | Required | Description |
|---|---|---|
| GitHubOwner | Optional | GitHub username owning the repo. |
| GitHubRepo | Optional | GitHub repo name (just the name, not the full URL). |
| GitHubOAuthToken | Optional | OAuth token used by AWS CodeBuild to connect to GitHub. |
| GitHubBranch | Optional | GitHub repo branch name. Default: master. |
The following parameters are only applicable if SourceCodeProvider is CodeCommit.
| Parameter | Required | Description |
|---|---|---|
| CodeCommitRepo | Optional | CodeCommit repository name (just the name, not the full URL). |
| CodeCommitBranch | Optional | CodeCommit repo branch name. Default: master. |
ArtifactsBucketArn- The S3 bucket ARN that stores artifacts for the pipeline such as input and output artifacts between stages.ArtifactsBucketName- The S3 bucket name that stores artifacts for the pipeline such as input and output artifacts between stages.PipelineName- The CodePipeline pipeline name.PipelineVersion- The CodePipeline pipeline version.
You must provide IAM roles in order to create Test and Deploy stages. IAM policies will be attached to the IAM roles that you provide. The sections below describe what IAM policies are attached to the IAM role for each stage.
In Test stage, the tests are run in AWS CodeBuild. IAM policies are attached to the provided IntegTestRole to grant permissions to CodeBuild to:
- Write logs to CloudWatch logs
- Read artifacts from previous stage in S3 artifacts bucket.
- Write artifacts to be used by later stage in S3 artifacts bucket.
Here is the IAM policy that will be attached to the provided IntegTestRole:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:<region>:<account>:log-group:/aws/codebuild/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::<artifacts-bucket>/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::<artifacts-bucket>"
],
"Effect": "Allow"
}
]
}
In deploy stage, the application is deployed using AWS CloudFormation. IAM policies are attached to the provided DeployRole to grant permissions to CloudFormation to:
- Read artifacts from previous stage in S3 artifacts bucket.
Here is the IAM policy that will be attached to the provided DeployRole:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::<artifacts-bucket>/*"
],
"Effect": "Allow"
}
]
}
This sample code is made available under the MIT-0 license. See the LICENSE file.