Widgetbook Cloud x GitHub

If you want to use Widgetbook Cloud with your existing GitHub 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 GitHub repository. You might need to connect your GitHub account to Widgetbook Cloud to access your repositories.

• Add API Key as a Secret

  Add WIDGETBOOK_API_KEY to your GitHub repository's secrets. You can find the API key in the Widgetbook Cloud's project settings page.

• Create GitHub Actions Workflow

  To upload a Widgetbook Build for each new commit in your repository, you need to setup up a workflow in GitHub Actions that runs on every push.

  name: Widgetbook Cloud Hosting
  on: push
  
  jobs:
    widgetbook-cloud-hosting:
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/checkout@v3
  
        - name: Setup flutter
          uses: subosito/flutter-action@v2
          with:
              channel: stable
  
        - name: Bootstrap App
          run: |
              flutter pub get
              # Add any other steps needed to make your
              # app widgets available for Widgetbook
  
        - name: Build Widgetbook
          working-directory: widgetbook
          run: |
              flutter pub get
              dart run build_runner build -d
              flutter build web -t lib/main.dart
  
        - name: Install Widgetbook CLI
          run: dart pub global activate widgetbook_cli
  
        - name: Push Widgetbook Build
          working-directory: widgetbook
          run: widgetbook cloud build push --api-key ${{ secrets.WIDGETBOOK_API_KEY }}
  

• Create a Pull Request

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

Enforcing reviews

Depending on your goals and workflow you might want to enforce reviews for all changes in your project requiring an accepted Widgetbook review for each pull requests with changes.

When Widgetbook Cloud reviews are enabled for your project, Widgetbook Cloud will automatically create a review for your PR and post the URL in your GitHub PR as a commit status. If changes are requested, the commit status will reflect the Widgetbook review status on your PR. However, the default configuration in GitHub allows for PRs to be merged even if the status checks are not passing or still pending.

To enforce reviews for all changes in your project, you can set up a branch protection rule in your GitHub repository. This will prevent PRs from being merged until the Widgetbook review is accepted.

• Open the rulesets settings page

  Navigate to the repository settings in GitHub. In the navigation, click on Rules to open the accordion. Then click on Rulesets to open the rulesets page.

  

• Set name

  Make sure to set a name for the new ruleset. For instance, set it to Widgetbook Review.

• Activate rulet

  Make sure to set the enforcement status to Active.

  

• Create new target

  Scroll down to the Targets section and click on Create target. Select make sure to select the branch you want to protect. We recommend to choose Include default branch but depending on your workflow you might want to choose one or multiple branches.

  

• Require status checks to pass

  On the page scroll down to the rules section. Make sure to disable the pre-selected rules. Once everything is deselected enable the rule Require status checks to pass.

  

• Add Widgetbook status check

  To make the Widgetbook Review commit status required, click the Add checks button. In the searchbox copy the name of the Widgetbook review status check which is formatted as Widgetbook Review (<widgetbook-project-name>). If you already have a pull-request with a Widgetbook Review commit status you can also obtain the name from the status checks section in the PR.

  

  In the example above the status check is named Widgetbook Review (widgetbook-explained).

  In the searchbox, select the item that is shown.

  

  Once the dropdown menu is deselected, the check will be added.

• Add a check source

  In case no source is configured, make sure to select the Widgetbook app as the source.

  

• Create the branch ruleset

  At the bottom of the page, make sure to press the Create button.

• Verify ruleset

  You can navigate to a PR to verify that the Widgetbook Review status check is now required to merge the PR.