Add Glimpse to Your Project

This guide adds automatic image optimization to an existing project. After your PR is merged, Glimpse checks for images that need optimization and opens another PR with the changes.

You do not need an account or a token of your own. The CLI uses a built-in public token for image commands, including CI checks and optimization.

Checks send image metadata. Optimization uploads the images that need processing.

#1. Run the CLI

Install cpx, then run:

cpx alias mathiasgrimm/glimpse-cli glimpse
cpx glimpse --help

Other options (a standalone PHAR, from source) are on the installation page.

#2. Scaffold the project files

From the project root:

cpx glimpse init --workflow-mode=optimize

Init creates these files:

• .glimpseignore: paths glimpse never scans, in gitignore syntax.
• .glimpse-baseline.json: the images you have already dealt with.
• .github/workflows/glimpse.yml: opens optimization PRs after merges and handles glimpse skip comments.

When init asks whether to accept current images unchanged, choose No. Leave the baseline empty so CI can check and optimize existing images too.

#3. Review the files and commit

Review .glimpseignore. Exclude generated assets, uploads, dependencies, and anything else Glimpse should not scan.

You can preview estimated savings locally before committing. This is optional. CI handles checking and optimization after merging.

Commit the scaffolded files:

git add .glimpseignore .glimpse-baseline.json .github/workflows/glimpse.yml
git commit -m "Add glimpse"

#4. Enable automatic optimization PRs

In Settings → Actions → General → Workflow permissions, enable Allow GitHub Actions to create and approve pull requests.

After each PR merge, the workflow checks for images that need optimization. If it finds any, Glimpse opens a PR with optimized images. Review the changes before merging. To keep an original, comment glimpse skip on that image in the PR.

Install the workflow on your default branch. Existing files are kept. To replace an existing workflow, run cpx glimpse init --workflow-mode=optimize --force. Review your custom settings before committing the replacement.

The workflow runs after a PR merges into any branch. It checks that branch and opens or updates an optimization PR against the same branch. A PR closed without merging does not run the job. The scan covers the repository, not just files changed in the merged PR. It does not merge the optimization PR for you.

The shared workflows use GITHUB_TOKEN. If GitHub asks for approval to run checks on the optimization PR, a user with write access can select Approve workflows to run. See GitHub's token documentation.

#From merge to review

1. 1

   #Your PR is merged

   Glimpse starts checking and optimizing your images automatically.

   

   Open full-size screenshot →

2. 2

   #Glimpse opens the optimization PR

   Glimpse opens a PR with the optimized images and instructions for keeping an original.

   

   Open full-size screenshot →

3. 3

   #You review the image changes

   Open Files changed to compare the original and optimized images and see the file size reduction.

   

   Open full-size screenshot →

4. 4

   #You keep an original if needed

   You comment glimpse skip on the image to restore the original and skip it until its contents change. Follow the instructions below.

   

   Open full-size screenshot →

#Keep an original image

On an automatic optimization PR, open Files changed. Add an inline comment on the image you want to keep:

glimpse skip

Post it as a single comment, or submit your review. The workflow restores that image from the commit recorded before optimization. It updates the same PR and replies when it finishes. You need repository write access. A general PR conversation comment does not select an image.

Wait for the confirmation before skipping another image. If the PR changed since you opened the diff, refresh it and comment on the latest version. If there is no confirmation, check the workflow run in Actions.

The baseline records via: "skip". Checks skip those exact bytes after the PR merges. If you change the image later, it is checked again. Merge the reviewed optimization PR before merging further image changes; a later optimization run can rebuild the automation PR from its base branch.

This works on open PRs in the same repository, including PRs you create manually. Existing workflows need to be regenerated with cpx glimpse init --workflow-mode=optimize --force. Review your custom settings before committing the replacement.

#Manually created PRs

Add the original commit to the PR description as a hidden comment:

<!-- glimpse-source: FULL_COMMIT_SHA -->

Replace FULL_COMMIT_SHA with the full SHA from git rev-parse <commit-before-optimization>. The commit must be an ancestor of the PR branch and contain the original image. The author and branch name do not need to match the automatic workflow. The same write-access and stale-head checks still apply.

For local changes, use glimpse skip. The automatic PR body also includes the command with its exact source commit. The command restores only from Git. It cannot recover an original that was never committed, and it does not create backups.

#The generated workflow

The generated file calls two reusable workflows from glimpse-cli. They handle PHP 8.5, cpx, checkout, optimization, PRs, and review comments. You do not need extra scripts in your repository.

The v1 tag follows compatible 1.x releases. You receive updates without editing the workflow, and moving to v2 remains your choice. The shared workflows use cpx with mathiasgrimm/glimpse-cli:^1.8, so the CLI also stays on a compatible 1.x release.

name: Automatic image optimization by Glimpse

on:
  pull_request_target:
    types: [closed]
  pull_request_review_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write

# In Settings → Actions → General → Workflow permissions, enable
# "Allow GitHub Actions to create and approve pull requests".
jobs:
  optimize-images:
    if: github.event_name == 'pull_request_target' && github.event.pull_request.merged == true
    uses: mathiasgrimm/glimpse-cli/.github/workflows/optimize-images.yml@v1
    secrets:
      GLIMPSE_TOKEN: ${{ secrets.GLIMPSE_TOKEN }} # Optional

  skip-image:
    if: github.event_name == 'pull_request_review_comment' && github.event.comment.body == 'glimpse skip'
    uses: mathiasgrimm/glimpse-cli/.github/workflows/skip-image.yml@v1

#What stays the same

Optimization keeps the image's format, dimensions, and exact filename. A .jpeg file keeps its .jpeg name. check --fix handles checking and optimization in one command.

An image above the CLI upload limit fails the job. Optimize it separately before committing. To accept existing images unchanged, run cpx glimpse analyze path/to/directory --update-baseline. This accepts all successfully analyzed images in that directory. Use .glimpseignore only for paths that should never be scanned.

The workflow uses the existing optimize default. You can optionally add with: to the optimize-images job:

    with:
      quality: '85'
      threshold: '25'

Both inputs are optional and use quoted values. quality accepts 1 to 100. threshold is the minimum estimated saving percentage (0 to 100, decimals allowed). Omitted inputs are not passed to the CLI, so it uses its own defaults. The current threshold default is 10. An explicit quality permits some quality loss. Metadata may be removed. The output is never larger than the input. Animated PNG, WebP, and AVIF files are returned unchanged; animated GIFs can be optimized.

check estimates savings for the best output format. A PNG flagged because AVIF could be smaller may save less, or nothing, when kept as PNG. The cpx glimpse optimize output in the job log shows the output size.

#Baseline and repeated runs

The workflow respects .glimpseignore and .glimpse-baseline.json. cpx glimpse optimize updates the existing baseline, including results that save zero bytes. The PR includes those updates with the images. After that PR merges, unchanged images are skipped.

A run with no changes creates no new PR. If an older optimization PR is no longer needed, the workflow removes its automation branch and closes it. Checking errors and failed optimization stop the job before publishing.

Seeding the baseline with cpx glimpse analyze . --update-baseline accepts images unchanged. The automatic workflow then skips them until their contents change. Leave the baseline empty if you want the first run to process all images reported by check.

Each destination branch gets its own automation branch and PR. The concurrency group is glimpse-optimize- followed by the destination branch. An active run finishes before another run for that branch starts. GitHub may replace a pending run with a newer one. Every run checks the latest branch contents, so it does not depend on processing every merge event.

The workflow uses pull_request_target to receive repository credentials for merged contributions, including contributions from forks. The optimization job checks out only the destination branch after merging. The comment job validates the writer, PR, and current commit before checking out that exact commit. It runs the published CLI with cpx --skip-local and refuses to push if the remote PR head changed after validation. Keep the merged guard and do not change checkout to the contributor's branch or run repository scripts in this job.

#Optional local preview

Before committing the setup, you can preview estimated savings locally:

cpx glimpse analyze .

This scans your images and reports estimated savings without changing them. It sends metadata, not image bytes. You do not need to run it before every PR. After you merge, the automatic workflow checks the images, optimizes those that need it, and opens a PR for you to review.

Leave off --update-baseline when previewing. That option accepts the images unchanged and makes CI skip them until their contents change.

#Optional: higher rate limits

For higher limits, create a personal token under Settings > API Tokens and run cpx glimpse auth locally. In CI, you can add it as a repository secret:

# Optional: for higher rate limits
gh secret set GLIMPSE_TOKEN

See CLI authentication for details. This is optional for automatic optimization.

#Where to go next

• CLI commands: convert, optimize, resize, and the rest.
• Analyze: how the estimates work.
• PHP SDK: the same operations from your application code.