Integration: GitLab

Integrate Ghost Inspector with GitLab

Search our documentation:

Toggle Documentation Menu

Integration: GitLab

Jump to...

Getting Started

To integrate with Ghost Inspector, you will need to use your API key, suite/test ID, and if testing against a local build, your ngrok token. It is highly recommended that you use the GitLab UI to create variables. This will allow you to mask the values in the logs and restrict them to protected branches. Just be careful with the protected setting, because if you have no protected branches, having that enabled for a variable will prevent it from being used in any build.

Test against public URL

If your GitLab CI/CD deploys to a publicly available URL, the simplest way to integrate Ghost Inspector is to use curl to execute a test or a suite.

.gitlab-ci.yml
deployment_job:
  stage: deploy
  script:
    # - your deploy step goes here
    - curl "https://api.ghostinspector.com/v1/tests/$GI_TEST/execute/?apiKey=$GI_API_KEY&startUrl=$START_URL"

You will need to replace $START_URL with the deployed URL. Use suites/$GI_SUITE (with a variable defined for your suite ID) to trigger a Ghost Inspector suite instead of a test.

Docker configurations

Although we have 2 different Docker images available, only the Node.js version has been proven to work with GitLab CI/CD. If you're familiar with Docker networking and GitLab, you are welcome try to use our standalone Docker image, but it has not been proven to work yet. More details on our Docker images can be found here.

Node.js App Example

Note: entrypoint needs to be disabled (as of our last testing) by setting it to an empty string, to avoid GitLab attempting to run commands in shell, which is not installed on our image. You can read more in this GitLab issue.

If your variables are defined in your project settings, which is recommended, they are automatically passed to the build containers defined in your .gitlab-ci.yml. They are included in the following example just for reference.

.gitlab-ci.yml
image:
  name: ghostinspector/test-runner-node
  entrypoint: [""]
variables:
  GI_API_KEY: $GI_API_KEY
  GI_SUITE: $GI_SUITE
  NGROK_TOKEN: $NGROK_TOKEN
  APP_PORT: 3000

before_script:
  - npm install
  - npm run build

# execute Ghost Inspector suite
ghost_inspector_test:
  script:
    - /bin/runghostinspectorsuite server.js

This uses our ghostinspector/test-runner-node Docker image. The before_script commands will run on our image, so if you need a package that is not installed, you'll need to either install it within your config or use a separate image.

Manual script configuration

If you are not using Docker (or do not wish to), you can still perform the same operations as our Docker containers manually, with a build script that interfaces with the ngrok and Ghost Inspector APIs directly. Use the example build script in our CircleCI integration docs as a starting point. Below is an example of how you would use the build script in GitHub actions specifically.

.gitlab-ci.yml
ghost_inspector_test:
  script:
    - bash build.sh

Trigger tests with GitLab webhooks

You can also trigger Ghost Inspector tests using GitLab's webhooks feature. Simply add a webhook pointing to our API and select when you would like it to be fired.

To trigger a suite, the API URL would look like this: https://api.ghostinspector.com/v1/suites/[suite-id]/execute/?apiKey=[api-key]. (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.
GitLab Webhooks