Introduction

To make AWS CodeBuild run only when code is pushed to master, you do not usually put that logic in buildspec.yml. The correct place is the source trigger configuration, typically a webhook filter. The exact setup depends on whether CodeBuild is connected directly to GitHub, GitLab, or Bitbucket, or whether your flow goes through CodePipeline or EventBridge.

The Right Mental Model

CodeBuild has two separate concerns:

• what commands run during the build, defined in buildspec.yml
• what events start the build, defined in the project trigger or surrounding pipeline

Branch filtering belongs to the second category. If you only gate inside buildspec.yml, the build still starts and consumes resources before your shell logic decides to exit.

Direct CodeBuild Webhooks

If your CodeBuild project is connected directly to a webhook-capable source provider, use a webhook filter that matches pushes to the master branch.

The key values are usually:

• event type: PUSH
• reference filter: ^refs/heads/master$

That reference pattern matches only pushes to the master branch.

An infrastructure-as-code example with CloudFormation looks like this:

1Resources:
2  BuildProject:
3    Type: AWS::CodeBuild::Project
4    Properties:
5      Name: my-build-project
6      ServiceRole: arn:aws:iam::123456789012:role/codebuild-service-role
7      Artifacts:
8        Type: NO_ARTIFACTS
9      Environment:
10        ComputeType: BUILD_GENERAL1_SMALL
11        Image: aws/codebuild/standard:7.0
12        Type: LINUX_CONTAINER
13      Source:
14        Type: GITHUB
15        Location: https://github.com/example/repo.git
16        BuildSpec: buildspec.yml
17      Triggers:
18        Webhook: true
19        FilterGroups:
20          - - Type: EVENT
21              Pattern: PUSH
22            - Type: HEAD_REF
23              Pattern: ^refs/heads/master$

That is the general shape you want for branch-specific direct triggers.

Why HEAD_REF Matters

AWS webhook filters use full refs, not just bare branch names. That is why the filter pattern uses:

^refs/heads/master$

instead of simply master.

If you match only master, the filter may not behave as expected because the event payload typically contains the full Git ref.

What If You Use CodePipeline Instead?

If CodeBuild is only one stage inside CodePipeline, then the branch filter is usually configured at the source stage, not inside CodeBuild.

In that setup:

• source stage watches one branch such as master
• source changes feed the pipeline
• CodeBuild runs only when the pipeline is started

That is a cleaner model if you already have a multi-stage CI or CD flow.

For GitHub-based pipelines, the source action usually has a branch field where you specify master. The same principle applies: filter before the build project is invoked.

CodeCommit Is Slightly Different

If your source lives in AWS CodeCommit, the most common pattern is to use CodePipeline or EventBridge rules that react to branch updates and then start the downstream build or pipeline.

In other words, “CodeBuild build only on push to master” may actually mean:

• EventBridge or CodePipeline watches CodeCommit master
• matching events start the build

The important part is still the same: the branch restriction lives in the trigger layer, not in the build commands.

Avoid Branch Checks Only Inside buildspec.yml

You can technically add shell logic like this:

1version: 0.2
2phases:
3  build:
4    commands:
5      - if [ "$CODEBUILD_WEBHOOK_HEAD_REF" != "refs/heads/master" ]; then exit 0; fi
6      - echo "Running real build"

This can be useful as a defensive guard, but it is not the best primary filter. The build still starts, the environment still spins up, and minutes are still consumed.

Use it only as a secondary safeguard when necessary.

Test the Filter Deliberately

A good validation sequence is:

1. push a commit to a non-master branch and confirm no build starts
2. push a commit to master and confirm the build starts
3. inspect the project’s webhook or trigger logs if the behavior is wrong

If builds trigger unexpectedly, the usual causes are:

• regex pattern too broad
• wrong filter type
• trigger actually configured in CodePipeline rather than the project itself
• source provider integration recreated with different defaults

Common Pitfalls

The biggest pitfall is putting branch filtering only in buildspec.yml and assuming that prevents builds from starting. It does not.

Another issue is using master as a literal branch string instead of matching the full ref refs/heads/master.

Teams also sometimes forget whether the trigger is owned by CodeBuild, CodePipeline, or EventBridge. If you edit the wrong layer, nothing changes.

Finally, many repositories now use main instead of master, so verify the branch name before debugging the filter logic.

Summary

• Filter branch-specific builds in the trigger configuration, not primarily in buildspec.yml.
• For direct CodeBuild webhooks, combine EVENT=PUSH with HEAD_REF=^refs/heads/master$.
• If you use CodePipeline or CodeCommit, the branch filter usually lives upstream of CodeBuild.
• 'buildspec.yml can provide a safety check, but it is not the efficient primary gate.'
• Always test the filter with both matching and nonmatching branch pushes.