Skip to main content

Preview generated images in PRs

Stoat can help you preview images generated as part of your build in a comment on your pull request. In the future you will be able to compare versions of an image with previous versions or the version in your main branch.

Here's an example of a Stoat comment with an image generated by the latest build:

image comment screenshot

Adding images to the Stoat comment​

  1. Set up Stoat with our getting started guide.

  2. Make sure the Stoat Action appears after the GitHub workflow step that generates your image.

    .github/workflows/your-workflow.yaml
    # existing step in your repo that generates an image
    - name: Build
      run: ./your-build-script.sh

    - name: Run Stoat Action
      uses: stoat-dev/stoat-action@v0
      if: always()

  3. Point Stoat at the generated image's path by adding a new task that uses the static_hosting plugin:

    .stoat/config.yaml
    ---
    version: 1
    enabled: true
    plugins:
      static_hosting:
        your-image-preview-id:
          path: path/to/image.jpg

    If you create a pull request, you should now have a link to the generated image in the Stoat comment after the build completes.

  4. (Optional) To embed the image preview directly in the comment, you will need a custom comment template.

    First of all, add a comment_template_file to your Stoat config file:

    .stoat/config.yaml
    ---
    version: 1
    enabled: true
    comment_template_file: ".stoat/comment.hbs"
    plugins:
      static_hosting:
        your_image_preview_id:
          path: path/to/image.jpg

    Then, create the Handlebars template file with Markdown to render the image directly in the comment:

    .stoat/comment.hbs
    ## Image Preview

    ![preview]({{ plugins.static_hosting.your_image_preview_id.link }})

    And that's it!

    caution

    If your image does not show in the comment when embedding the image directly, it's possible that you are exceeding GitHub's 10mb size limit for image embeds. Unfortunately, when this limit is exceeded, no error is shown; the image simply does not show. You will either need to reduce the size your image or use a link instead of embedding the image directly.

Example Repo​

See a real build that generates an image and embeds it in a Stoat comment in this pull request.

15min Video Tutorial​

Here's an in-depth video tutorial going over the process of setting up image previews for the example pull request above.