github-codebuild-logs

This serverless app solves a common complaint when using AWS CodeBuild as a CI solution: PR contributors don't have access to the build logs if the CI build fails on their PR branch. The app creates publicly accessible links to PR build logs for a given AWS CodeBuild project and posts them as a comment on the corresponding GitHub PR.

Here is an example GitHub PR comment:

App Architecture

1. Contributors create or update a PR.
2. Assuming AWS CodeBuild is already setup as the CI solution for this repo, the PR triggers a new CI build.
3. Once the CI build completes (success or failure), a CloudWatch Event triggers an AWS Lambda function.
4. If the event is for a PR build, the Lambda function
   1. copies the build log to an S3 bucket. Note, the build log auto-expires after a configurable number of days (default: 30).
   2. publishes a comment on the GitHub PR with a publicly accessible link to the logs. Note, the app uses the CodeBuild project's GitHub OAUTH token to post the comment.
5. The logs link goes to an API Gateway endpoint, which redirects to a pre-signed URL for the build logs in the S3 bucket.

Installation Instructions

To attach this app to an existing AWS CodeBuild project in your AWS account,

1. Go to the app's page on the Serverless Application Repository and click "Deploy"
2. Provide the CodeBuild project name and any other parameters (see parameter details below) and click "Deploy"

Alternatively, if your CodeBuild project is defined in an AWS SAM template, this app can be embedded as a nested app inside that SAM template. To do this, visit the app's page on the AWS Lambda Console. Click the "Copy as SAM Resource" button and paste the copied YAML into your SAM template.

If you are an AWS CDK user, you can use the aws-serverless.CfnApplication construct to embed this app in your CDK application. Here is a TypeScript example:

import serverless = require('@aws-cdk/aws-sam');

new serverless.CfnApplication(this, 'GitHubCodeBuildLogsSAR', {
  location: {
    applicationId: 'arn:aws:serverlessrepo:us-east-1:277187709615:applications/github-codebuild-logs',
    semanticVersion: '1.5.0'
  },
  parameters: {
    CodeBuildProjectName: project.projectName
  }
});

App Parameters

1. CodeBuildProjectName (required) - Name of CodeBuild project this app is posting logs for.
2. ExpirationInDays (optional) - Number of days before a build's log page expires. Default: 30
3. CodeBuildProjectCustomLogGroupName (optional) - If the CodeBuild Project has a custom log group name, you can specify it here. If not provided, the app will assume the CodeBuild default log group name format of /aws/codebuild/<project name>.
4. GitHubOAuthToken (optional) - OAuth token used for writing comments to GitHub PRs. If not provided, the app will attempt to pull an OAuth token from the CodeBuild project. Note, if your CodeBuild project does not have a GitHub OAuth token, e.g., it is being used to build a public GitHub repo, then this parameter will be required for the app to function properly.
   • NOTE: The access token used requires public_repo permissions for public repositories or repo for private repositories.
5. DeletePreviousComments (optional) - Set to true to delete previously posted PR comments before posting a new one. Default: false
6. LogLevel (optional) - Log level for Lambda function logging, e.g., ERROR, INFO, DEBUG, etc. Default: INFO
7. CommentOnSuccess (optional) - Set to false to not publish a comment when build is successful. Default: true
8. BuildEventTimeout (optional) - Timeout for Process Build Event Lambda. Default: 60

App Outputs

1. ProcessBuildEventsFunctionName - ProcessBuildEvents Lambda function name.
2. ProcessBuildEventsFunctionArn - ProcessBuildEvents Lambda function ARN.
3. BuildLogsBucketName - Build logs S3 bucket name.
4. BuildLogsBucketArn - Build logs S3 bucket ARN.

Security Considerations

The following precautions are taken when the GitHubOAuthToken parameter is provided since it's sensitive data:

1. The NoEcho option is used on the parameter so the value will never be shown by CloudFormation.
2. The app stores the value in AWS Secrets Manager.

License Summary

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