Add a monthly image-compression check to GitHub Actions

A CI image-compression job is easy to add and easy to make noisy. If it scans the whole repository on every run, it can spend quota on unchanged assets. If it writes results back into its own inputs, later runs may process those results again. The safer pattern is narrow: identify changed image files, process only those, and make the output location explicit.

PiPic’s open-source CLI, published as @pipic/cli on npm, is intended for scripts, CI and developer workflows. Its free tier covers 100 images per month; Pro covers 5,000. Treat those as image counts, not as a reason to compress the entire repository on every push.

Choose what the job owns

Start by deciding whether CI should replace source assets or create a separate compressed output. PiPic’s CLI supports atomic in-place replacement or writing to a fresh directory. A separate output directory makes the pipeline boundary easier to see: source files remain inputs, and compressed files are generated artifacts. It also reduces the risk of a later run treating its own output as new source material.

Pick the asset paths the job is responsible for. For example, a repository might include a dedicated directory for web images. Filter for the formats PiPic compresses—JPG, PNG, WebP and AVIF—and exclude generated output, fixtures, or files that should remain untouched. Keeping that scope small is more reliable than trying to optimize every image-like file in a repository.

Build the GitHub Actions flow

1. Choose a trigger. Run the job on pull requests, pushes to the relevant branch, or both. A pull-request run gives maintainers a chance to inspect compressed output before it is merged; a post-merge run can instead generate files for a later commit or deployment step.
2. Find changed assets. Have the workflow compare the proposed change with its base and produce a list of added or modified image paths. Exclude deleted files: there is nothing to compress. For a push, compare against the prior revision; for a pull request, compare against its target branch. Use that list as the job’s input rather than passing the entire asset directory.
3. Install and authenticate the CLI. Install @pipic/cli in the runner using the package’s documented setup and invocation instructions. PiPic says to sign in once so scripts and CI can run unattended afterward. Follow its documented CI authentication procedure. If that procedure requires a credential, store it as a GitHub Actions secret and provide it to the job without writing it into the repository or logs.
4. Compress and handle the result. Invoke the CLI on the changed-file list and choose either in-place replacement or a fresh output directory. Use the documented CLI syntax; don’t assume flags or environment-variable names. Then decide what happens to the result: the workflow can make it available for review, or a later repository step can incorporate it according to your team’s normal process.

This is a GitHub Actions workflow that runs PiPic’s CLI, not a claim that you need a separate PiPic-specific action. Keeping the steps explicit makes it clearer which paths are processed and where the output goes.

Keep the quota predictable

Count images sent for processing across workflow runs, and compare that total with the monthly tier you use. A changed-file filter limits unnecessary work, but it does not guarantee you will stay under a quota: a large asset import or repeated runs can still consume it. Avoid rerunning the compression job when the input list has not changed, and check how your workflow handles retries before enabling automatic reruns.

For a small site, the free tier’s 100 images per month may be enough if CI processes only changed files. Teams regularly processing more can plan around the 5,000-image Pro tier. Do not assume that the quota is a per-run allowance; budget by month and track actual workflow inputs.

Before making the job required, test it with a small change. Confirm that it selects only the intended files, preserves the expected extensions, and places output where reviewers or later steps can find it. PiPic describes its output as staying in the original format, which is useful when URLs or build rules depend on file extensions. For more on that trade-off, see why retaining image formats can matter in existing web systems.

Make the first run boring

Start with one directory and a handful of changed images. Inspect the diff, verify that a second run with no image changes has no compression work to do, and watch the image count over the month. Expand the path scope only after that behavior is stable. A CI asset pipeline is useful when it catches the right files without surprising contributors—or quietly spending its monthly allowance on everything else.