Trigger CodePulse reviews from GitHub Actions

Drop the CodePulse composite action into your CI workflow and the review runs automatically after your tests pass — no Slack paste, no waiting for a human to nudge the bot. Authentication is handled via GitHub's built-in OIDC provider, so there are no secrets to configure.

This page covers the full setup, the contract with the endpoint, every error state, and how to debug each one.

Quick start

jobs:
  test:
    # ... your existing tests
  lint:
    # ... your existing lint

  codepulse:
    needs: [test, lint]
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - uses: codepulsehq/review-action@v1

Three things are happening here:

1. needs: [test, lint] — GitHub Actions will only run the codepulse job once every job listed here has finished successfully. This is your lever for saying "review only once the essentials are green."
2. permissions: id-token: write — required. This lets the runner mint a short-lived OIDC token that identifies the workflow run. No token, no authentication.
3. uses: codepulsehq/review-action@v1 — the composite action itself. It has one optional input (api-url) that you'd only override for staging or self-hosted deployments.

Prerequisites

Before adding the action:

1. Install the CodePulse GitHub App. If your repo or organization isn't already connected to CodePulse, install the app from your CodePulse dashboard — the action can't post reviews to a repo it has no install on.
2. Enable the github_action_trigger feature flag in your dashboard under Settings → Triggers. This is opt-in so workspaces don't start auto-dispatching without an explicit choice.

That's it. No API keys to rotate, no webhook URLs to configure, no per-repo setup beyond installing the app.

How it works

When your codepulse job runs:

1. The GitHub Actions runner asks GitHub's OIDC provider for a signed JWT identifying this exact workflow run. The token's audience is codepulse — a CodePulse-specific binding that means the token can't be silently reused against a different service.
2. The action POSTs {oidc_token, pr_number, head_sha} to https://review.codepulsehq.com/github/action-trigger.
3. CodePulse verifies the JWT against GitHub's public JWKS, extracts the repository owner and name from the claims, and looks up which CodePulse workspace owns that org.
4. If the workspace is active, the flag is on, the PR author is licensed, and the monthly quota has capacity, CodePulse dispatches a review task. The review is posted back to GitHub as the CodePulse bot.
5. The action logs a GitHub Actions annotation summarising what happened (::notice::, ::warning::, or ::error::) and exits.

Supported events

Only pull_request events are supported in v1. Workflows triggered by push, workflow_dispatch, schedule, or anything else will be rejected with auth_failed.

Fork PRs cannot trigger reviews. GitHub does not grant id-token: write to workflows running from forks — that's a GitHub security feature, not something CodePulse enforces. External contributors' PRs still get reviewed through the normal webhook path when a maintainer installs the app at the org level.

Exit codes and annotations

The action maps each possible outcome to a GitHub Actions annotation and an exit code. The design principle: your CI only turns red when something you can fix is wrong. Operator-side problems (quota, billing, our infrastructure) warn but don't break your merges.

Situation	Exit	Annotation
Review queued	0	::notice::
Already in flight for this SHA	0	::notice::
Head SHA has moved since workflow started	0	::warning::
Couldn't fetch the PR to verify head SHA	0	::warning::
Monthly quota exhausted	0	::warning::
PR author not licensed	0	::warning::
Feature flag disabled	0	::warning::
CodePulse API unreachable	0	::warning::
CodePulse App not installed on this repo	1	::error::
OIDC authentication failed	1	::error::

When to worry

• Exit 1 means the action can't do its job without configuration changes from you. Follow the error message — usually "install the app" or "add permissions: id-token: write to this job."
• Warning, exit 0 means CodePulse noticed the job but chose not to dispatch (quota, flag, author). Check your dashboard. Your CI stays green so a broken month of billing doesn't block unrelated merges.
• Notice, exit 0 is the happy path — review is either running or already did.

Runner support

The action uses bash. Linux and macOS runners work out of the box. Windows runners are not supported in v1 — the script assumes a POSIX shell.

Troubleshooting

"OIDC token env missing"

The job is missing permissions: id-token: write. Add it at the job level (not the workflow level — that's a separate GitHub Actions concept):

jobs:
  codepulse:
    permissions:
      id-token: write   # ← this line
    # ...

If it's already there and you're still seeing this error, check that the workflow is running in response to a pull_request event (not push or schedule — those are unsupported in v1).

"CodePulse App not installed"

The repository's owner doesn't have the CodePulse GitHub App installed, or the app is installed but the action couldn't find an active workspace for that owner. Visit the CodePulse dashboard, confirm the GitHub App is linked to your workspace, and re-run the workflow.

"Head SHA has moved since this workflow started"

You pushed a new commit while the first workflow was still running. The action refuses to dispatch a review against a stale SHA — the new workflow run (on the new SHA) will handle the review. This is a warning, not an error, because it's expected during active development.

"github_action_trigger is disabled for this workspace"

The feature flag is off for your workspace. Turn it on at Settings → Triggers in the dashboard.

"Monthly review quota exhausted"

You've hit your plan's review cap for the month. Either wait for the next billing cycle or upgrade your plan from the dashboard. The action exits 0 here so unrelated merges aren't blocked by a billing state.

"Author not licensed"

The PR author doesn't have a CodePulse seat in your workspace. A workspace admin needs to approve them at Settings → Seats. Until then, this particular author's PRs won't get reviews from this trigger path.

"CodePulse unreachable"

Network error reaching review.codepulsehq.com. Transient — retry the workflow. If it persists across multiple attempts, check the CodePulse status page or contact support.

Security

• No secrets on your side. OIDC tokens are short-lived (minutes) and bound to this specific workflow run. There's nothing to rotate and nothing to leak.
• Audience binding. The action requests tokens with audience codepulse; our endpoint rejects tokens with any other audience. A token minted for, say, AWS deploys cannot be silently replayed against CodePulse.
• Installation-scoped. Reviews post as the CodePulse GitHub App using the installation token for the target org. The action never gains access to a repo the app isn't installed on.

Pairing with other triggers

The GitHub Action trigger doesn't replace the other ways to invoke CodePulse — it complements them:

• Slack paste (paste a PR URL into Slack) — fastest for one-off reviews and reviews of PRs that predate adding the action.
• pull_request.review_requested webhook — triggers when anyone explicitly requests CodePulse as a reviewer on GitHub.
• CI-trigger via branch protection — if you already use required status checks on the branch, CodePulse can auto-dispatch when they all pass, no workflow changes required. Enabled by the separate ci_trigger feature flag.
• This GitHub Action — explicit, deterministic, per-repo control over which jobs gate the review.

You can use several in parallel; per-PR dispatch is deduped by head SHA so you won't get double reviews.

FAQ

Does the action run my code?

No. The action runs trigger.sh, which does two curl calls — one to GitHub's OIDC provider, one to the CodePulse API. It doesn't read your source, doesn't invoke npm install, doesn't execute anything from your repo.

How long does it take?

The action itself finishes in 1-3 seconds (OIDC token fetch + API call). The actual review runs on our infrastructure and posts to GitHub typically within 2-5 minutes depending on PR size.

What if I want to pin to a specific version?

Use a tagged ref: uses: codepulsehq/review-action@v1.0.0. Or pin to a commit SHA for maximum stability. The @v1 tag floats with minor and patch releases within the v1 major.

Can I run this in multiple workflows?

Yes. Per-PR dispatch is deduplicated by head SHA on our side — if two workflows fire the action at the same time for the same commit, exactly one review runs. A new push creates a new head SHA and gets a fresh review.