Automatically Compress Images on Pull Requests

Calibre’s new GitHub Action allows you to compress raster images with minimal setup automatically. Never ship unoptimised graphics again.

Understand the impact of imagery#

According to the 2025 Web Almanac, the median home page ships 911 KB of images on mobile and 1,058 KB on desktop. Whether we like it or not, images are here to stay. We use them to assist in portraying our brands, visualise messaging, run retail stores, and so much more.

Because images are the single largest contributor to page weight, ahead of both JavaScript and fonts, it becomes crucial to ensure media is appropriately optimised and served fast. Not only we want to avoid adding further page bloat, but also ensure our customers aren’t presented with unintentionally blank spaces or drain their data allocation with massive downloads.

There are numerous tactics to remedy the performance impact caused by imagery. From strategic decisionmaking; judging if images are necessary at all, what format is the most suitable; to nitty-gritty implementation; automatic resizing, lazy loading and content delivery networks. Turns out, responsibly managing your images is a complicated job.

One of the lowest hanging fruit in achieving highly performant imagery is automating the compression process. It’s easy to accidentally add an uncompressed file or run out of time to set up elaborate configurations to manage compression for us.

Fortunately, with GitHub Actions, it’s now possible to trigger various workflows directly where your code lives. Actions make it possible to introduce a wide range of performance-oriented tooling.

Add automatic image compression to your Pull Requests#

Because it’s Calibre’s mission to make the Web faster, we’ve created a freely available GitHub Action that automatically optimises images in your Pull Requests.

The action uses sharp and libvips to compress JPEGs, PNGs, WebPs and AVIFs. Compression is quality-based rather than lossless: the defaults are jpegQuality: '85' and pngQuality: '80', which cut file size hard at a difference you will struggle to see. Every quality setting is configurable, so you can trade fidelity for bytes in either direction. What’s excellent about embedding a compression step directly in the developer platform (or CI) rather than in local development environments (or relying on drag-and-drop tools) is that no image can hit production uncompressed. This empowers any contributors with basic knowledge of GitHub to update images without introducing performance regression and saves everyone time.

Adapt the action to your workflow#

Two configuration options make Image Actions fit around how your team already works:

• compressOnly mode skips the commit and the summary comment, so you can handle those steps yourself. It is also how you work around GitHub Actions not being able to alter pull requests that arrive from forked repositories.
• On-demand and scheduled runs mean compression isn’t limited to open pull requests. Pair a workflow_dispatch or schedule trigger with compressOnly and the create-pull-request action, and Image Actions will raise a pull request for any images that slipped through uncompressed.

Both options, and the full set of quality settings, are documented in the Image Actions README.

You can add automatic image compression to your repositories directly from GitHub Action Marketplace. Don’t forget about continuously tracking the performance of your sites. If your focus is to reduce image-induced sluggishness, pay special attention to Largest Contentful Paint: on most pages the largest element is an image, so compression shows up there first. Transferred Image Size tells you how much weight you have shed, and Cumulative Layout Shift will catch images that load without reserved space.

Happy optimising!