Widgetbook Cloud x GitLab

If you want to use Widgetbook Cloud with your existing GitLab repository, here's a step-by-step guide to help you get started.

• Setup Widgetbook Cloud Project

  Create a new project in Widgetbook Cloud by importing your GitLab repository. You might need to connect your GitLab account to Widgetbook Cloud to access your repositories.

• Add API Key as a Variable

  Add WIDGETBOOK_API_KEY to your GitLab's CI/CD Variables. You can find the API key in the Widgetbook Cloud's project settings page. Make sure you uncheck "Protect variable" checkbox, to allow the variable to be accessible from feature branches.

• Create GitLab CI/CD Pipeline

  To upload a Widgetbook Build for each new commit in your repository, you need to setup up a pipeline in GitLab CI/CD that runs on every push.

  Create a new GitLab pipeline file in your repository under .gitlab-ci.yml with the following content:

  image: ghcr.io/cirruslabs/flutter
  
  stages:
    - widgetbook
  
  widgetbook_cloud_hosting:
    stage: widgetbook
    script:
      # Bootstrap App
      - flutter pub get
      - flutter gen-l10n
      # Bootstrap Widgetbook
      - cd widgetbook
      - flutter pub get
      - dart run build_runner build -d
      - flutter build web
      # Upload to Widgetbook Cloud
      - dart pub global activate widgetbook_cli
      - export PATH="$PATH":"$HOME/.pub-cache/bin"
      - widgetbook cloud build push --api-key "$WIDGETBOOK_API_KEY"
  

• Create a Merge Request

  To test out if everything works properly, create a new branch and push a commit to it, then submit a MR with the new branch. After the build upload finishes, a commit status will be added to your MR once the Widgetbook Review is ready.

Troubleshooting

To make sure that your Widgetbook Cloud setup works properly, you can check that your repository has a Webhook configured (under Project Settings > Webhooks) to notify Widgetbook Cloud about new MRs.

GitLab Merged Result Pipelines

If you are using GitLab Merged Result Pipelines, that means your pipeline runs on a commit that is not in your MR branch (i.e. the merged result commit). In this case, the commit status from Widgetbook Cloud needs to be added to that "merged result" commit, to be visible in the MR, and block the merge if the Widgetbook Review fails.

To achieve this, replace the cloud build push command as follows:

widgetbook:
  script:
    - # Previous scripts...
    - widgetbook cloud build push --api-key "$WIDGETBOOK_API_KEY"
    - |
      if [ "$CI_PIPELINE_SOURCE" == "merge_request_event" ]; then
        # Upload a merged result build
        widgetbook cloud build push \
          --api-key "$WIDGETBOOK_API_KEY" \
          --commit "$CI_MERGE_REQUEST_SOURCE_BRANCH_SHA" \
          --branch "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" \
          --merged-result-commit "$CI_COMMIT_SHA"
      else
        # Upload a regular build
        widgetbook cloud build push --api-key "$WIDGETBOOK_API_KEY"
      fi