/aws-sam-codepipeline-cd

A serverless app that sets up an AWS CodePipeline pipeline for a given GitHub repo. This app allows people developing SAM applications to quickly get CodePipeline-based CD setup for their project.

MIT No AttributionMIT-0

AWS SAM CodePipeline CD Build Status

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.

Pipeline Structure

When this application is deployed, it will create an AWS CodePipeline pipeline that has up to the following 5 stages:

  1. Source: This stage is the entry point of the pipeline. It is triggered when you push a change to the specified Git repository branch.
  2. Build: This stage builds the project using AWS CodeBuild.
  3. Test (optional): This stage runs the integration tests of the project using CodeBuild. This stage will only be created if you provide the IntegTestRoleName parameter when setting up this module. See the "Parameters" section below.
  4. Deploy (optional): This stage deploys the project using CloudFormation. This stage will only be created if you provide the DeployRoleName parameter when setting up this application. See the "Parameters" section below.
  5. 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 PublishToSAR parameter when setting up this module. See the "Parameters" section below.

Here is an example CodePipeline pipeline that has all 5 stages: aws-sam-codepipeline-cd-pipeline-example

Installation

  1. Create an AWS account if you do not already have one and login
  2. If your source code repository is on GitHub, then create a GitHub OAuth token (see instructions below).
  3. Go to this app's page on the Serverless Application Repository and click "Deploy"
  4. Provide the required app parameters and click "Deploy"

Creating a GitHub OAuth token

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.

GitHub OAuth Token Permissions

Parameters

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.

Outputs

  1. ArtifactsBucketArn - The S3 bucket ARN that stores artifacts for the pipeline such as input and output artifacts between stages.
  2. ArtifactsBucketName - The S3 bucket name that stores artifacts for the pipeline such as input and output artifacts between stages.
  3. PipelineName - The CodePipeline pipeline name.
  4. PipelineVersion - The CodePipeline pipeline version.

IAM Roles in Test and Deploy stages

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.

Test 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"
        }
    ]
}

Deploy stage

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"
        }
    ]
}

License Summary

This sample code is made available under the MIT-0 license. See the LICENSE file.