GitHub Actions

Use the GitHub Actions integration when a deployment should automatically run a Killbug test plan. The workflow calls the webhook URL generated by a test plan trigger.

Before you start

Create or edit a test plan, add a Webhook trigger, and copy the generated Webhook URL. Store it as a GitHub Actions repository secret named KILLBUG_WEBHOOK_URL.

If each deployment has a different URL, also store that URL in a repository or environment variable named KILLBUG_BASE_URL. Killbug will use this value for the run when the workflow sends overrideBaseUrl.

Workflow file

Save this file as .github/workflows/killbug-post-deploy.yml:

name: Killbug post-deploy

on:
  deployment_status:

permissions:
  contents: read

jobs:
  test:
    if: >-
      github.event.deployment_status.state == 'success' &&
      github.event.deployment.environment == 'production'
    runs-on: ubuntu-latest

    steps:
      - name: Trigger Killbug
        env:
          GH_TOKEN: ${{ github.token }}
          WEBHOOK_URL: ${{ secrets.KILLBUG_WEBHOOK_URL }}
          OVERRIDE_BASE_URL: ${{ vars.KILLBUG_BASE_URL }}
          REPOSITORY: ${{ github.repository }}
          COMMIT_SHA: ${{ github.event.deployment.sha }}
        run: |
          COMMIT_MESSAGE="$(gh api "repos/$REPOSITORY/commits/$COMMIT_SHA" --jq '.commit.message')"

          jq -n \
            --arg message "[github] $COMMIT_MESSAGE" \
            --arg overrideBaseUrl "$OVERRIDE_BASE_URL" \
            '{ message: $message } + if $overrideBaseUrl == "" then {} else { overrideBaseUrl: $overrideBaseUrl } end' |
          curl --fail-with-body \
            -X POST "$WEBHOOK_URL" \
            -H "Content-Type: application/json" \
            --data-binary @-

What the workflow sends

The webhook payload includes:

• message: shown on the Killbug run so reviewers can connect the run to the GitHub deployment.
• overrideBaseUrl: optional. When present, Killbug tests this URL instead of the project's default Base URL.

Use a message that is meaningful during failure review. Commit messages, release names, deployment IDs, or environment names are usually enough.

Deployment timing

The example listens for GitHub deployment_status events and only runs after GitHub reports a successful production deployment. This avoids testing the previous version immediately after code is pushed.

If your host does not report deployment status back to GitHub, trigger Killbug after your deploy step instead:

- name: Deploy
  run: ./scripts/deploy.sh

- name: Trigger Killbug
  env:
    WEBHOOK_URL: ${{ secrets.KILLBUG_WEBHOOK_URL }}
  run: |
    jq -n --arg message "[github] $GITHUB_SHA deployed" '{ message: $message }' |
    curl --fail-with-body \
      -X POST "$WEBHOOK_URL" \
      -H "Content-Type: application/json" \
      --data-binary @-

Preview and staging environments

For preview deployments, set overrideBaseUrl to the preview URL:

jq -n \
  --arg message "[github] preview $GITHUB_SHA" \
  --arg overrideBaseUrl "$PREVIEW_URL" \
  '{ message: $message, overrideBaseUrl: $overrideBaseUrl }'

Only point a test plan at an environment where its credentials, test data, and permissions are prepared to run. A production test plan may fail against a preview app if the preview environment does not have the same users, billing state, or feature flags.

Verification

Action: Merge or deploy a change that should create a successful GitHub deployment status.

Expected result: GitHub Actions runs Killbug post-deploy, the curl step returns a successful response, and a new Killbug run appears for the test plan with trigger Webhook.

Action: Open the Killbug run and review the failed or passed test cases.

Expected result: The run message includes the GitHub context sent by the workflow, and any failures include the normal browser evidence for review.

Troubleshooting

• 401 or 404: regenerate the test plan Webhook URL, save the test plan, and update KILLBUG_WEBHOOK_URL.
• curl: (22): inspect the response body printed by --fail-with-body.
• No run appears: confirm the test plan still has a Webhook trigger and the workflow condition matches the deployment environment.
• Run targets the wrong app: check whether overrideBaseUrl is being sent, and verify the project's Base URL.