GitHub

If you would like to trigger your Ghost Inspector tests or suites through GitHub, you can do this via their webhooks feature. If you would like the test or suite results integrated into the status of your commits and pull requests, you will also need to activate our Ghost Inspector integration with your GitHub account. Alternatively, you can integrate using GitHub Actions.

Table of Contents

Activate Ghost Inspector’s GitHub Integration

To enable GitHub integration for your personal account or organization, go to your account page and click on “Integrations”. You’ll see the GitHub logo under available services.

Note: Enabling Ghost Inspector’s GitHub integration is only necessary for sending statuses to GitHub. The scope of the integration allows us to update statuses only. It does not allow us to access your account or repositories.

Ghost Inspector Integrations

Click the “Connect Service” button and follow the instructions. You’ll need to log into your GitHub account. Once GitHub is connected, our API will automatically send statuses to the associated commits when webhooks are triggered (See setup below).

Add Ghost Inspector Webhooks to GitHub

Simply add a webhook pointing to our API and select when you would like it to be fired. You can add as many as you’d like to trigger various tests or suites. To trigger a suite, the API URL would look like this: https://api.ghostinspector.com/v1/suites/[suite-id]/execute/?apiKey=[api-key]&immediate=1. (You will need to swap in your own values for [suite-id] and [api-key].)

Note: This example assumes that you want to execute a suite after your project has been pushed. For other options, please see our API documentation.

GitHub Webhooks

If you’ve activated our GitHub integration above, statuses will automatically be sent to GitHub when these webhooks are triggered.

GitHub Statuses

Upating GitHub Commit Statuses from 3rd-Party Tools

There are some scenarios where you already have Github integrated with a 3rd-party system (such as a build/CI server) but still want to trigger a Ghost Inspector test (or suite) and update the commit status for your pull request on Github. Assuming you have activated Ghost Inspector’s Github integration, this can be accomplished manually by passing a few extra parameters along with your execute API call:

Note This API call will return immediately just as if you passed the parameter immedate=1.
$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-GitHub-Event: push" \
    -d '{"payload": "{\"repository\": {\"statuses_url\": \"https://api.github.com/repos/<github-organization>/<github-repo>/statuses/<sha>\"},\"sha\": \"<sha>\"}"}' \
    "https://api.ghostinspector.com/v1/tests/<test-id>/execute/?apiKey=<api-key>"

Let’s break down each line and see what’s happening:

  • curl -X POST this is instructing curl that we’re using a POST request
  • -H "Content-Type: application/json"</code> specify the content type header for json`
  • -H "X-GitHub-Event: push" specify the header to simulate a Github push event
  • -d '{"payload": "…"}' simulate the Github event payload, but only the minimum necessary for our system to post back to Github. Note that the payload value must be a string of escaped JSON. You will need to update the {{my-organization}} and {{my-repo}} values to reflect your Github organization and repository, as well as {{sha}} as the actual commit status to be updated
  • On the last line you’ll need to change{{my-test}} to your Ghost Inspector test ID and {{my-api-key}} to your Ghost Inspector API key. Also, if you want to execute a suite instead of a test, you’ll need to change the API call to execute suite

Now when you execute this API call, you will see your Github status update to show the pending status until your test is finished:

GitHub Pending Status for Ghost Inspector Test