CDK TypeScript project to set up the CodeGuru Reviewer CI/CD integration

This repo contains a CDK Stack that sets up CodeGuru Reviewer GitHub Action in your AWS account for CI/CD integration in GitHub. It sets up the correct permissions for using CodeGuru Reviewer as well as creating an S3 bucket that holds the code and build artifacts for analysis by CodeGuru Reivewer.

Before we get started

If you do not have the CDK for TypeScript installed, follow the instructions here and make sure your credentials are set up correctly so you can deploy with CDK. The steps include:

npm install typescript aws-cdk

Once everything is set up correctly, fetch the dependencies and compile:

git clone https://github.com/aws-samples/aws-codeguru-reviewer-cicd-cdk-sample.git
cd aws-codeguru-reviewer-cicd-cdk-sample
npm install
npm run build

Specify which organizations can use CodeGuru Reviewer

In the file ./cdk.json, add all GitHub repositories that should be allowed to use CodeGuru Reviewer in the allowedGithubRepos list. For example:

"allowedGithubRepos": ["aws-samples/*", "awslabs/smithy"]

allows all repositories in the organization aws-sample and the repository awslabs/smithy to use CodeGuru Reviewer.

Deploy the Stack to your account

Once you have updated the allowedGithubRepos, you need bootstrap CDK and deploy the stack.

1) CDK Bootstrap

Run the command:

npx cdk bootstrap --profile {PROFILE_NAME} "aws://unknown-account/unknown-region"

• Replace PROFILE_NAME with one of the named profiles in your ~/.aws/config file.
• No need to replace the text in quotes. You can literally use "aws://unknown-account/unknown-region".
• You only need to boostrap once.

2) CDK Deploy

Run the command:

npx cdk deploy --profile {PROFILE_NAME}

• Replace PROFILE_NAME with one of the named profiles in your ~/.aws/config file.

3) Take note of the created resource names

Once the deployment completes, you will receive an output similar to this:

 ✅  GuruCdkSetupStack

Outputs:
GuruCdkSetupStack.Role = arn:aws:iam::123456789012:role/GitHubActionRole
GuruCdkSetupStack.Region = us-east-1
GuruCdkSetupStack.Bucket = codeguru-reviewer-build-artifacts-123456789012-us-east-1

You will need this information in your GitHub workflow:

• You will use the Role ARN and Region when calling the configure-aws-credentials action.
• You will use the Bucket name when calling the codeguru-reviewer action.

Add the workflow to your GitHub repositories

You can use one of the following templates for your workflow:

Example for a Java project that builds with Gradle

name: Analyze with CodeGuru Reviewer

on: 
 - push
 - workflow_dispatch # This allows manual triggering of the action through the GitHub UI.

permissions:
    id-token: write
    contents: read
    security-events: write 

jobs:
  analyze:
    name: Analyze with CodeGuru Reviewer
    runs-on: ubuntu-latest
    steps:
    - name: Configure AWS credentials
      id: iam-role
      continue-on-error: true
      uses: aws-actions/configure-aws-credentials@v1
      with:
        role-to-assume: {ROLE_ARN}
        aws-region: {REGION}
    
    - uses: actions/checkout@v2
      if: steps.iam-role.outcome == 'success'
      with:
        fetch-depth: 0
    - name: Set up JDK 1.8
      if: steps.iam-role.outcome == 'success'
      uses: actions/setup-java@v1
      with:
        java-version: 1.8
    - name: Build project
      if: steps.iam-role.outcome == 'success'
      run: ./gradlew jar -x test

    - name: CodeGuru Reviewer
      uses: aws-actions/[email protected]
      if: steps.iam-role.outcome == 'success'
      continue-on-error: false
      with:          
        s3_bucket: {BUCKET_NAME}
        build_path: ./target/classes

    - name: Upload review result
      if: steps.iam-role.outcome == 'success'
      uses: github/codeql-action/upload-sarif@v1
      with:
        sarif_file: codeguru-results.sarif.json

Replace the strings {ROLE_ARN}, {REGION}, and {BUCKET_NAME} with the values that you received as output from CDK.

These examples uses GitHub's Code Scanning feature to display the recommendations. If you are using a private repository without paying for Code Scanning, this will fail. Before you can use this feature, you need to enable GitHub Code Scanning for your repository or organization (see documentation). If you are not planning on using this feature, omit the Upload review result part.

Example for a Python project

name: Analyze with CodeGuru Reviewer

on: 
 - push
 - workflow_dispatch # This allows manual triggering of the action through the GitHub UI.

permissions:
    id-token: write
    contents: read

jobs:
  analyze:
    name: Analyze with CodeGuru Reviewer
    runs-on: ubuntu-latest
    steps:
    - name: Configure AWS credentials
      id: iam-role
      continue-on-error: true
      uses: aws-actions/configure-aws-credentials@v1
      with:
        role-to-assume: {ROLE_ARN}
        aws-region: {REGION}
    
    - uses: actions/checkout@v2
      if: steps.iam-role.outcome == 'success'
      with:
        fetch-depth: 0

    - name: CodeGuru Reviewer
      uses: aws-actions/[email protected]
      if: steps.iam-role.outcome == 'success'
      continue-on-error: false
      with:          
        s3_bucket: {BUCKET_NAME}
        
    - name: Store SARIF file
      if: steps.iam-role.outcome == 'success'
      uses: actions/upload-artifact@v2
      with:
        name: SARIF_recommendations
        path: ./codeguru-results.sarif.json

Replace the strings {ROLE_ARN}, {REGION}, and {BUCKET_NAME} with the values that you received as output from CDK.

Here, instead of uploading the artifacts to GitHubs security tab, we store them as artifacs of the CICD run. This allows anyone with access to the repository to download the recommendations in SARIF format.

You can also see all recommendations in you AWS Console.

For more information, see the CodeGuru Reviewer documentation.

Note that only allow-listed organizations and repositories can assume the IAM Role to run CodeGuru Reviewer. For this reason, we recommend that you run the CodeGuru Reviewer Action only on push events. The action will only succeed on pull_requests if the repository from which the pull_request originated is also part of the allow list.

Further, to avoid failures of the Action for users who fork this repository, we label the Role assumption step with id: iam-role and guard all other workflow steps with:

if: steps.iam-role.outcome == 'success'

so they do not get executed if the fork is not allowed to assume the Role.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.