CircleCI GitHub App PR Triggers: How to Access Base Branch in Workflow Conditions

ByPriya Nair

The answer: pipeline.event.github.pull_request.base.ref

If you’re using CircleCI’s GitHub App integration and need the base branch of a pull request — the branch your PR is targeting — the pipeline value is pipeline.event.github.pull_request.base.ref. It works in workflow when conditions and can be interpolated into bash steps. The pipeline.trigger_parameters.webhook.body.* path never worked reliably for GitHub App triggers, and pipeline.git.base_revision comes back empty for PR-triggered runs because it’s designed for push contexts, not PR events.

Why the old trigger_parameters paths fail

There are two separate problems here. First, pipeline.trigger_parameters.webhook.body gives you an empty object ({}) under GitHub App triggers — the raw webhook payload isn’t surfaced there. Second, pipeline.trigger_parameters.github_app.ref returns the head ref (the PR branch), not the base, so even when it compiles it gives you the wrong thing.

There’s also a looming expiry date. CircleCI announced that all values under pipeline.trigger_parameters.circleci.* and pipeline.trigger_parameters.github_app.* will stop being guaranteed as of August 1, 2026. The replacements are three new namespaces: pipeline.trigger.*, pipeline.event.*, and pipeline.git.*. If you’re still using the old paths anywhere, now is a good time to migrate.

Key old-to-new mappings

  • pipeline.trigger_parameters.github_app.ref → pipeline.event.github.pull_request.head.ref (PR events) or pipeline.event.github.ref (push events)
  • pipeline.trigger_parameters.github_app.repo_name → pipeline.event.github.repository.name
  • pipeline.trigger_parameters.github_app.user_name → pipeline.event.github.sender.login

There is no replacement for a raw webhook body blob — the new namespaces expose the specific fields you need as first-class pipeline values, which is the right approach anyway.

Workflow when condition: PR targeting main only

Combine the event name check (which you already found works) with the base ref check:

workflows:
  pr-checks:
    when:
      and:
        - equal: [pull_request, pipeline.event.name]
        - equal: [main, pipeline.event.github.pull_request.base.ref]
    jobs:
      - sonarqube-scan

The equal operator takes a two-element list: the constant first, then the pipeline value. Both conditions together mean the workflow only fires on PR events where the target branch is exactly main. The value is a short branch name — compare against "main", not "refs/heads/main".

Because your main branch is not the default branch on GitHub, this explicit base ref check is essential. CircleCI’s default branch detection won’t save you here.

Passing the base ref into SonarQube

Use the << >> interpolation syntax to inject the pipeline value into a step command at compile time:

jobs:
  sonarqube-scan:
    steps:
      - run:
          name: Run SonarQube scanner
          command: |
            sonar-scanner \
              -Dsonar.pullrequest.branch=$CIRCLE_BRANCH \
              -Dsonar.pullrequest.base=<< pipeline.event.github.pull_request.base.ref >> \
              -Dsonar.pullrequest.key=$CIRCLE_PULL_REQUEST

$CIRCLE_BRANCH is the head (PR) branch. $CIRCLE_PULL_REQUEST is the PR URL — this environment variable is now populated for GitHub App pipelines following a recent CircleCI update. And << pipeline.event.github.pull_request.base.ref >> expands to the target branch name at pipeline compile time, so SonarQube gets exactly what it needs to run PR-mode analysis.

Why pipeline.git.base_revision comes back empty

This one surprises people. pipeline.git.base_revision is supposed to represent the last commit on the base branch that the current branch diverged from. For push-triggered pipelines CircleCI can compute that. For PR-event-triggered pipelines it often can’t, so it returns an empty string. Don’t use it for conditionals — it’s not reliable in this context. Stick to pipeline.event.* values for anything PR-related.

The checkout_sha compile error

pipeline.trigger_parameters.github_app.checkout_sha appears in the pipeline values documentation but throws a compile error in YAML condition expressions. The value is available as an environment variable inside bash steps, but the dot-drilling logic in CircleCI’s expression compiler doesn’t support it. If you need the SHA in bash, $CIRCLE_SHA1 is always available and always works.

Sources

Similar Posts