Catesta - AWS CodeBuild Integration¶

Synopsis¶

Scaffolds a new PowerShell module or vault project intended for CI/CD workflow using AWS CodeBuild.

Getting Started¶

Note: It is important to have a clear understanding of what your project should support before starting with Catesta. If your goal is to create a cross-platform solution or test multiple versions of PowerShell, consider running multiple build types to ensure proper functioning on various platforms and environments.

CodeBuild Supported Builds:

You will need an AWS Account.
Create your project using Catesta and select [C] AWS CodeBuild at the CICD prompt. (Catesta Basics)
- Note: You will see the following prompt unique to the AWS CodeBuild selection:
  - Enter S3 bucket name to download needed PS modules from S3 location. Leave blank to DL modules from PSGallery. Your CodeBuild instance will need various modules to successfully build your PowerShell module project. By default, it does not contain them. Leaving this blank will default to having the CodeBuild instance download and install the needed modules from the PSGallery during each build. You can improve build times and performance by instead loading the required modules into an S3 bucket. If you choose to do so, you can specify the S3 bucket here. Don't forget to give your CodeBuild project permission to that S3 bucket.
Create your CodeBuild project(s) in your AWS account. While you can do this manually, using the CloudFormation (CFN) template generated by Catesta is recommended.
- GitHub
  - Upload the CFN template to AWS CloudFormation to deploy the required resources automatically. The template adapts to include support for any build types you've chosen during the Catesta setup, such as Windows, Linux, or macOS.
  - CodeBuild projects currently use OATH to authenticate with GitHub. You need to configure OATH for CodeBuild before you deploy the CFN template. Reference Adding CodeBuild OATH to your Project Repository below for configuring this.
  - Note: The GitHub process in the template does not automatically configure artifact generation. You may modify the template to include artifact generation if required.
  - Don't forget to copy your badge URL to display on your project
- Bitbucket
  - Upload the CFN template to AWS CloudFormation to deploy the required resources automatically. The template adapts to include support for any build types you've chosen during the Catesta setup, such as Windows, Linux, or macOS.
  - CodeBuild projects currently use OATH to authenticate with Bitbucket. You need to configure OATH for CodeBuild before you deploy the CFN template. Reference Adding CodeBuild OATH to your Project Repository below for configuring this.
  - Note: The Bitbucket process in the template does not automatically configure artifact generation. You may modify the template to include artifact generation if required.
  - Don't forget to copy your badge URL to display on your project
- GitLab
  - Upload the CFN template to AWS CloudFormation to deploy the required resources automatically. The template adapts to include support for any build types you've chosen during the Catesta setup, such as Windows, Linux, or macOS.
  - CodeBuild projects currently use CODECONNECTIONS to authenticate with GitLab. You need to configure CODECONNECTIONS for CodeBuild before you deploy the CFN template. Reference Adding CodeBuild CODECONNECTION to your Project Repository below for configuring this.
  - Note: The GitLab process in the template does not automatically configure artifact generation. You may modify the template to include artifact generation if required.
  - Don't forget to copy your badge URL to display on your project
- CodeCommit
  - - Upload the CFN template to AWS CloudFormation to deploy the required resources automatically. The template adapts to include support for any build types you've chosen during the Catesta setup, such as Windows, Linux, or macOS.
  - Note: The CodeCommit does include artifacts. Artifacts built from your main branch will be stored in a primary s3 bucket. All other branches will have artifacts stored in a development bucket.
Write the logic for your module (the hardest part)
- All build testing can be done locally by navigating to src and running Invoke-Build
  - By default, this runs all tasks in the build file.
    - If you want to run a specific task from the build file you can provide the task name. For example, to just execute Pester tests for your project: Invoke-Build -Task Test
- If using VSCode as your primary editor you can use VSCode tasks to perform various local actions
  - Open the VSCode Command palette
    - Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux) or F1
  - Type Tasks: Run Task
  - Select the task to run
    - Examples:
      - task . - Runs complete build (all tasks)
      - task Test - Invokes all Pester Unit Tests
      - task Analyze - Invokes Script Analyzer checks
      - task DevCC - Generates generate xml file to graphically display code coverage in VSCode using Coverage Gutters
Add any module dependencies to your CI/CD bootstrap file: install_modules.ps1
Upload to your desired repository which now has a triggered/monitored build action.
Evaluate results of your build and display your AWS CodeBuild badge proudly!

Test Reports¶

Catesta automatically configures your AWS CodeBuild PowerShell project to generate detailed Tests and Code Coverage reports:

AWS CodeBuild PowerShell project Test results

AWS CodeBuild PowerShell project Code Coverage results

Deploying the CFN (CloudFormation) Template¶

Adding CodeBuild OATH to your Project Repository¶

AWS documentation for ProjectSource states that OAUTH should be set for GitHub and Bitbucket.

In order to accomplish source provider access to your project's repo using OATH, you will first need to configure CodeBuild in the AWS Console.

This needs to be done prior to deploying your CFN template.

Essentially, you just need to login to your AWS console, create a new CodeBuild project, and under source, add a source to your supported repository location. You will be prompted to enter your credentials to establish a link. Once complete, CodeBuild will be aware of this OATH link. You do not actually need to create the project in the console. Once you've created the OATH link, you can click Cancel on the new CodeBuild project creation page.

Catesta AWS CodeBuild OATH Link Create

Adding CodeBuild CODECONNECTION to your Project Repository¶

AWS documentation for ProjectSource states that CODECONNECTIONS should be set for GitLab.

In order to accomplish GitLab connections to your project's repo using CODECONNECTIONS, you will first need to configure CodeBuild in the AWS Console.

This needs to be done prior to deploying your CFN template.

Essentially, you just need to login to your AWS console, create a new CodeBuild project, and under source, add a new connection. You will be prompted to enter your credentials to establish a link. Once complete, CodeBuild will have a new connection under the Connections tab. You do not actually need to create the project in the console. Once you've created the CODECONNECTIONS link, you can click Cancel on the new CodeBuild project creation page.

Catesta AWS CodeBuild CODECONNECTION Link Create

Once created, you will need to capture the CodeStar CodeConnection Arn under the connections tab. This ARN is a required parameter input for your CFN template

Catesta AWS CodeBuild CODECONNECTION Link Create

Manual CFN upload example¶

The following shows the GitHub CFN example:

Catesta PowerShell AWS CodeBuild CFN Example

Final CFN Deployment Results example¶

AWS CodeBuild projects created by Catesta

Notes¶

This template currently supports three repository sources that the user can specify when invoking the template:

If you elect to host your code in GitHub or Bitbucket you will need to manually associate your AWS account with your GitHub account. This is a one time manual action. See CFN notes above.

You may wish to use different CodeBuild projects to monitor different branches of your repository. This can be done with a WebhookFilter:

AWS CodeBuild Project WebhookFilter