§ Docs · kelp/check

kelp/check.

Adds a required security check to your pull requests. Kelp scans the PR head commit for new critical or high findings against the base branch, posts one comment with the verdict, and fails the check when the PR introduces gating issues.

Prerequisites

Install the Kelp GitHub App on your repo's org.
Connect the repo at kelp.build/dashboard.

Add the workflow

When you connect a repo, Kelp opens a PR automatically that adds this file. If you prefer to add it by hand, or if you closed the auto-opened PR, drop this into .github/workflows/kelp-check.yml in your repo.

name: kelp/check
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: kelp-security/kelp-action@v1

No API keys, no secrets. The workflow's ephemeral GITHUB_TOKEN authenticates the request to Kelp.

Make it a required check

The workflow runs on every PR by default but doesn't block merges on its own. To gate merges through Kelp:

Open the first PR that triggers the workflow so GitHub registers it as a status check.
Go to Settings → Branches → Branch protection rules for main.
Enable "Require status checks to pass before merging", search for kelp/check, and mark it as required.

Inputs

kelp-url

default: https://kelp.build

Kelp API base URL. Override for staging or self-hosted deployments.

github-token

default: ${{ github.token }}

Token used to authenticate the workflow's identity to Kelp. Defaults to the ephemeral workflow token — you shouldn't need to override.

fail-on

default: critical,high

Comma-separated severities that fail the check when introduced by the PR. Add medium or low to widen the gate.

poll-timeout-seconds

default: 300

How long the Action waits for the scan to finish. Increase for large repos.

Troubleshooting

repo_not_connected — check fails immediately

The repo isn't linked to a Kelp project yet. Sign in at kelp.build/dashboard and connect it, then re-run the check.

invalid_github_token / repo_mismatch

Your workflow's permissions: block is missing contents: read. Add it and re-run.

Timed out after 300s

First scans on large repos can take longer. Bump poll-timeout-seconds to "600".

No comment on the PR

Check that the Kelp GitHub App has Pull requests: write permission on your install. If you installed before this was added, accept the new permissions from GitHub.

← Back to dashboard