AWS CodeBuild
User Guide (API Version 2016-10-06)

Bitbucket Pull Request and Webhook Filter Sample for CodeBuild

This sample shows you how to create a pull request using a Bitbucket repository. It also shows you how to use a Bitbucket webhook to trigger CodeBuild to create a build of a project.

Bitbucket Pull Request Prerequisites

To run this sample you must connect your AWS CodeBuild project with your Bitbucket account.

Note

CodeBuild has updated its permissions with Bitbucket. If you previously connected your project to Bitbucket and now receive a Bitbucket connection error, you must reconnect to grant CodeBuild permission to manage your webhooks.

Create a Build Project with Bitbucket as the Source Repository and Enable Webhooks

The following steps describe how to create an AWS CodeBuild project with Bitbucket as a source repository and enable webhooks.

  1. Open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

  2. If a CodeBuild information page is displayed, choose Create project. Otherwise, on the navigation pane, expand Build, and then choose Build projects.

  3. On the Create build project page, in Project configuration, for Project name, enter a name for this build project. Build project names must be unique across each AWS account. You can also include an optional description of the build project to help other users understand what this project is used for.

  4. In Source, for Source provider, choose Bitbucket.

    Follow the instructions to connect or reconnect, and then choose Grant access.

    Note

    CodeBuild does not support Bitbucket Server.

  5. Choose Use a repository in my account. You cannot use a webhook if you use a public Bitbucket repository.

  6. In Primary source webhook events select Rebuild every time a code change is pushed to this repository. You can select this check box only if you chose Repository in my Bitbucket account.

    Note

    If a build is triggered by a Bitbucket webhook, the Report build status setting is ignored. The build status is always sent to Bitbucket.

  7. Choose other settings for your project. For more information about source provider options and settings, see Choose source provider.

  8. Choose Create build project. On the Review page, choose Start build to run the build.

Trigger a Build with a Bitbucket Webhook

For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code.

  1. Open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

  2. On the navigation pane, choose Build projects, and then choose a project associated with a Bitbucket repository with webhooks. For information about creating a Bitbucket webhook project, see Create a Build Project with Bitbucket as the Source Repository and Enable Webhooks.

  3. Make some changes in the code in your project's Bitbucket repository.

  4. Create a pull request on your Bitbucket repository. For more information, see Making a Pull Request.

  5. On the Bitbucket webhooks page, choose View request to see a list of recent events.

  6. Choose View details to see details about the response returned by CodeBuild. It might look something like this:

    "response":"Webhook received and buld started: https://us-east-1.console.aws.amazon.com/codebuild/home..." "statusCode":200
  7. Navigate to the Bitbucket pull request page to see the status of the build.

Filter Bitbucket Webhook Events

You can use webhook filter groups to specify which Bitbucket webhook events trigger a build. For example, you can specify that a build is triggered for specified branches only.

You can specify more than one webhook filter group. A build is triggered if the filters on one or more filter groups evaluate to true. When you create a filter group, you specify:

  • An event. For Bitbucket, you can choose one or more of the following events: PUSH, PULL_REQUEST_CREATED, and PULL_REQUEST_UPDATED.

  • One or more optional filters. Use a regular expression to specify a filter. For an event to trigger a build, every filter associated with it must evaluate to true.

    • ACTOR_ACCOUNT_ID (ACTOR_ID in the console): A webhook event triggers a build when a Bitbucket account ID matches the regular expression pattern.

    • HEAD_REF: A webhook event triggers a build when the head reference matches the regular expression pattern. For example, refs/heads/branch-name and refs/tags/tag-name.

    • BASE_REF: A webhook event triggers a build when the base reference matches the regular expression pattern. A BASE_REF filter works with pull request events only. For example, refs/heads/branch-name.

Filter BitBucket Webhook Events (Console)

To use the AWS Management Console to filter webhook events:

  1. Select Rebuild every time a code change is pushed to this repository when you create your project.

  2. From Event type, choose one or more events.

  3. To filter when an event triggers a build, under Start a build under these conditions, add one or more optional filters.

  4. To filter when an event is not triggered, under Don't start a build under these conditions, add one or more optional filters.

  5. Choose Add filter group to add another filter group.

For more information, see Create a Build Project (Console) and WebhookFilter in the AWS CodeBuild API Reference.

In this example, a webhook filter group triggers a build for pull requests only:

Using an example of two filter groups, a build is triggered when one or both evaluate to true:

  • The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression ^refs/heads/master$ and head references that matches ^refs/heads/branch1!.

  • The second filter group specifies push requests on branches with Git reference names that match the regular expression ^refs/heads/branch1$.

In this example, a webhook filter group triggers a build for all requests except tag events.

In this example, a webhook filter group triggers a build only when a change is made by a Bitbucket user that does not have an account ID that matches the regular expression actor-account-id.

Note

For information about how to find your Bitbucket account ID, see https://api.bitbucket.org/2.0/users/user-name, where user-name is your Bitbucket user name.

Filter BitBucket Webhook Events (SDK)

To use the AWS CodeBuild SDK to filter webhook events, use the filterGroups field in the request syntax of the CreateWebhook or UpdateWebhook API methods. For more information, see WebhookFilter in the CodeBuild API Reference.

To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax:

"filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED" } ] ]

To create a webhook filter that triggers a build for specified branches only, use the pattern parameter to specify a regular expression to filter branch names. Using an example of two filter groups, a build is triggered when one or both are evaluate to true:

  • The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression ^refs/heads/master$ and head references that match ^refs/heads/myBranch$.

  • The second filter group specifies push requests on branches with Git reference names that match the regular expression ^refs/heads/myBranch$ and .

"filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" }, { "type": "BASE_REF", "pattern": "^refs/heads/master$" } ], [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" } ] ]

You can use the excludeMatchedPattern parameter to specify which events do not trigger a build. In this example, a build is triggered for all requests except tag events.

"filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED" }, { "type": "HEAD_REF", "pattern": "^refs/tags/.*", "excludeMatchedPattern": true } ] ]

You can create a filter that triggers a build only when a change is made by a Bitbucket user with account ID actor-account-id.

Note

For information about how to find your Bitbucket account ID, see https://api.bitbucket.org/2.0/users/user-name, where user-name is your Bitbucket user name.

"filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED" }, { "type": "ACTOR_ACCOUNT_ID", "pattern": "actor-account-id" } ] ]

Filter Bitbucket Webhook Events (AWS CloudFormation)

To use an AWS CloudFormation template to filter webhook events, use the AWS CodeBuild project's FilterGroups property. The following YAML-formatted portion of a AWS CloudFormation template creates two filter groups. Together, they trigger a build when one or both evaluate to true:

  • The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression ^refs/heads/master$ by a Bitbucket user that does not have account ID 12345.

  • The second filter group specifies push requests are created on branches with Git reference names that match the regular expression ^refs/heads/.*.

CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/java:openjdk-8 Source: Type: BITBUCKET Location: source-location Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/master$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: HEAD_REF Pattern: ^refs/heads/.*