GitLab Integration

Screenshotbot can be configured to update build statuses on your GitLab Merge Requests. Users can accept or reject screenshot changes from the build link in GitLab, and the changes are immediately reflected in GitLab.

Setting up credentials

First, you need to create a GitLab Personal Access Token for Screenshotbot. (If you're unable to share an Access Token with Screenshotbot, you can perform the GitLab API access yourself by using our Webhook integration)

From your User Preferences, choose Access Tokens on the left. Give your token a name, and make sure it has access to api.

When you click Create Personal Access Token, it will show you the personal access token for you to copy. Make sure the token does not expire.

Security Tip! You can create a user with restricted access to limit the scope of the access token to individual repositories.

Configuring Screenshotbot

On Screenshotbot, go to Settings -> GitLab. Here you need to provide the GitLab URL and the personal access token.

If you're using the SaaS version of GitLab, you can leave the GitLab URL as https://gitlab.com. If you're using a self-hosted version (either Enterprise or Open-source), you can provide the URL here.

Click Save to save the settings to Screenshotbot. After you save the settings, you can use the Test Settings option to verify that the integration is correctly set up.

From this point onward, you can configure your CLI to upload screenshots. For an example see here, but your CI config will depend on platform you're testing.

You can configure environment variables with the Screenshotbot API key and secret in your project's settings at Settings->CI/CD->Variables.

Reviewing changes

When we detect changed screenshots on a Merge Request, we'll send a failure build status:

Clicking the link will let you review the changes and Accept or Reject them.

On accepting the changes, we'll update the build status back to green, with a note about who reviewed the changes.

Auditing API Usage

Screenshotbot keeps a log of every API request we make to GitLab on your behalf. This log can be used to get an understanding of how we use the GitLab token you provide us. Additionally, if any request fails, the failure reasons will be listed here. This can be helpful to debug any integration issues.

Webhook integration

If you're unable to share an Access Token with Screenshotbot, we also supports sending Webhook notifications to a server you control. You can then forward these requests to your GitLab server.

First, make sure you enable Webhooks on your Screenshotbot organization by following the instructions in our Webhooks documentation.

Then, on the GitLab settings page, make sure the Enable Webhooks is checked:

If you're using Webhooks, you do not need to provide an Access Token.

From this point onward, your Webhook listener will get a callback with a payload of gitlab.update-build-status.

This arguments of this payload can directly be passed to GitLab's Build Status API. Contact us for help with this integration.

Where to go from here

We've only touched upon our integration with GitLab. In order to complete your integration, you might also have to integrate with your platform libraries (e.g. Android or iOS projects)

We have many examples of how these integrations look like on our GitHub organization page.