Tracking the AWS CodePipeline build status from the third-party Git repository

AWS CodePipeline allows you to use a third-party Git repository as a source for a pipeline, however, the status of the build may not be available on the 3rd party git repository dashboard. As a developer, it is preferable to see the build / pipeline status in the same dashboard when working with repository. This blog walks you through building a solution that will feed in pipeline / build status to the 3rd party repository, making it easy for the developer to track status without switching context.

CodePipeline supports GitHub and Bitbucket, and both provides a REST API that you can use to push information related to pipeline runs back to your repository. This post explains how to set up this integration between CodePipeline and a Git repository.

Overview of solution

When you configure CodePipeline with a third-party repository as the source, the pipeline is triggered when a commit is pushed to repository. In our solution, when the pipeline runs, every status change is pushed as an event to an Amazon Simple Notification Service (Amazon SNS) topic. An AWS Lambda function processes this information and pushes the status back to the repository via a REST API.

You can view the status of your pipeline directly in your third-party Git repository (Bitbucket or GitHub) instead of needing to use the CodePipeline console. The following diagram illustrates this architecture.

To implement this solution, we complete the following high-level steps:

1. Create REST API credentials for our repository (Bitbucket or GitHub).
2. Deploy the provided AWS CloudFormation template to create the necessary resources.
3. Test the Git integration.

Prerequisites

For this walkthrough, you should have the following prerequisites:

• An AWS account
• An existing CodePipeline pipeline set up with Bitbucket or GitHub as source code provider (for more information, see Bitbucket connections or GitHub connections, respectively)
• A GitHub or Bitbucket account to generate the required API credentials
• The AWS Identity and Access Management (IAM) role AWSServiceRoleForCodeStarNotifications for AWS CodeStar notifications
• The following CloudFormation template downloaded, which sets up the infrastructure for your integration

Create the third-party source code provider API credentials

We first create credentials that allows our Lambda function to communicate with our repository (Bitbucket or GitHub).

Bitbucket

If you’re using Bitbucket, create your credentials (app password) with the following steps:

1. Sign in to your Bitbucket account.
2. On the Personal Settings menu, under Access Management, choose App Password.
3. Choose Create app password.
4. For Label, enter a label to identity your password in the future.
5. Under Permissions, for Repositories, select Write.
6. Choose Create.

For more information, see the Bitbucket API documentation.

GitHub

For GitHub, follow these steps to create a personal access token:

1. Sign in to your GitHub account.
2. Under Settings, choose Developer settings.
3. Choose Personal access tokens.
4. Choose Generate new token.
5. For Note, enter a description of the token.
6. For Select scopes, select repo:status.
7. Make sure to copy and store your created access token, because you can only view it once.

For more information, see GitHub REST API.

Deploy your CloudFormation template

To create the SNS topic, Lambda function, CodePipeline notification rule, and associated resources, we use AWS CloudFormation. Download and save the provided CloudFormation template and name the file cloudformation.yaml, then complete the following steps:

1. On the AWS CloudFormation console, choose Create stack.
2. Choose the option to use new resources.
3. Upload the saved template file.
4. For Stack name, enter a name for the stack.
5. For IntegrationPass, enter the password that was generated in the previous step for creating account credentials.
6. For IntegrationType, choose Bitbucket or GitHub.
7. For IntegrationUser, enter the Bitbucket or GitHub login used to create access in the previous step.
8. For PipelineName, enter name of the pipeline in CodePipeline where you want to set up the notification integration.
9. Choose Next.
10. Step through the remaining pages.
11. On the final page, select the acknowledgement that IAM resources can be created.
12. Choose Create stack.

If stack creation fails, you might see the following error message:

AWS CodeStar Notifications could not create the AWS CloudWatch Events managed rule in your AWS account. If this is your first time creating a notification rule, the service-linked role for AWS CodeStar Notifications might not yet exist. Creation of this role might take up to 15 minutes.

To fix this, make sure that the IAM role AWSServiceRoleForCodeStarNotifications was created by AWS CodeStar. Then delete the failed CloudFormation stack and provision it again.

Test the integration

To test your integration, make a commit in your source Git repository where CodePipeline runs the pipeline. The pipeline status update should be visible on the repository website itself, under the list of commits.

The following screenshot shows a list of commits for a Bitbucket repository (https://bitbucket.org/${workpace}/${repository}/commits/).

The following screenshot shows a list of commits for a GitHub repository (https://github.com/${owner}/${repository}/commits/main).

Clean up resources

To avoid incurring future charges, remember to delete the resources deployed by the CloudFormation template in the previous steps.

Conclusion

When you can see the status of a pipeline from your Git repository, you can see important code-related information more easily. This solution allows for seamless navigation between your Bitbucket or GitHub repository and CodePipeline. You can now focus on the code review process, or merge code between branches without switching between consoles to view the pipeline status.