Git integrations

By default, Backlight offers Git integrations with four different providers:

  • Github
  • Gitlab
  • Bitbucket
  • Azure

Set-up

You can use any of these providers to create a repository and Backlight will complete the set-up upon creation, either via registering webhooks on your repository, or via the provider's app installation (i.e. Github).

Token usage

We have defined and set up different OAuth clients for each provider in Backlight.

Backlight uses each of these Oauth integrations to retrieve, generate and refresh tokens, in order to accomplish tasks on your behalf.

For Github: Backlight uses the Github app's token.

You can revoke tokens at anytime, Backlight will try to refresh with your authenticated user.

Git usage

Backlight uses integrations as bare Git client, allowing you to:

  • Push a commit to a remote repository
  • Pull a branch from a remote repository
  • Hard reset of a branch from a remote repository

API Provider usage

  • List repositories for a specific provider
  • Get username of the user within a provider
  • Create and update a Pull/Merge request based on a commit

Events usage

After correctly setting up your repository, Backlight will automatically register webhooks (or application events for Github), in order to be notified of certain events.

Specifically, Backlight will listen for:

  • Merge events
  • Pull/Merge request events

Merge events

Backlight uses these events to keep your default branch up-to-date in Backlight.

It will also allow you to:

  • Keep track of the baseline when you need to create a new branch inside Backlight
  • Keep track of the baseline for visual screenshots

Once Backlight receives a merge event from the configured Git provider on the default branch, Backlight captures the sha of the default branch and Backlight stores it, to be able to later fetch the default branch in c

Pull/Merge request events

Backlight uses every create, update, delete event for the Pull/Merge request events.

create

This event will populate the list of the Pull/Merge requests available inside Backlight.

It will also trigger the computation of our CI/Review integration.

update

This event, like the create event, will also trigger our CI/Review integration.

delete

This event will delete the Pull/Merge requests available inside Backlight.

CI/Review integration

Once a Pull/Merge request has been captured, Backlight will run two steps: pre-check & visual review. This is to help you review the Pull/Merge request.

Pre-check

Backlight will do a dry-run publish, ensuring your design system can still be published with those modification on your repository.

Our Git integration will also add a build status/check and a comment inside the Pull/Merge request, indicating that the next step of the review is ready.

Visual review

Backlight will compute screenshots of all your stories for all your components, and even for your documentation pages.

Backlight will compare those screenshots to the baseline of your default branch.

Once this comparison is done, if the visual diff detects an error in pixels above 2% then this screenshot will be labeled with the status error, otherwise it will be considered a success.

With these statuses, Backlight will publish a summary status/check in your Pull/Merge request, within your favorite Git provider.

In the meantime, Backlight calculates a Review Page for you, where you can comment and approve the Pull/Merge request manually if any of errors have been detected.

Review UI

Backlight also leverages the API of your Git provider so you can interact directly with the Pull/Merge request UI Backlight built for you.

You can navigate through all components that have been detected with errors in the left panel.

All visual errors are highlighted with a red beam.

You can also choose to inspect the whole processing of the Pull/Merge request with Backlight by deactivating the filter on errors.

In the right panel, Backlight will present N panels corresponding to all files inside a component. If there is any diff, it will allow you to inspect with live representation of the before and after of you stories or documentation. You can also access the snapshots by clicking on the ellipsis and selecting the display of screenshots instead of the live view.

You can mark each accordion (representing either a file or a snapshot) by clicking on the checkbox Viewed. This will collapse and reduce the visuals to review (highly inspired by Github's diff view).

Add comment to a Pull/Merge request

On each visual (story or documentation page), you can add a comment. This comment will go through the Git integration and the comment will be added to your Pull/Merge request.

Backlight will forge a message with the two screenshots to keep track of the visuals when the comment has been made.

Validate a Pull/Merge request

Once your review for a particular Pull/Merge request is done, you can either accept or deny, or simply add a general comment to the Pull/Merge request.

Backlight will add this status or comment to your Pull/Merge request, directly inside your favorite Git provider.