Image Actions

Image Actions automatically compresses JPEG, PNG and WebP images in GitHub Pull Requests.

Fast, efficient and near-lossless compression
Uses the best image compression algorithms available: mozjpeg and libvips
Configurable and extensible: use default settings or adapt to your needs
Runs in GitHub Actions
Built by web performance experts at Calibre; a performance monitoring platform

Image Actions

Installation

Create the .github/workflows/calibreapp-image-actions.yml file with the following configuration:

name: Compress images
on:
  pull_request:
    # Run image-actions when jpg, jpeg, png or webp files are added or changed
    # See https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpushpull_requestpaths
    paths:
      - '**.jpg'
      - '**.jpeg'
      - '**.png'
      - '**.webp'
jobs:
  build:
    # Only run on Pull Requests within the same repository, and not from forks
    if: github.event.pull_request.head.repo.full_name == github.repository
    name: calibreapp/image-actions
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@master

      - name: Compress Images
        uses: calibreapp/image-actions@master
        with:
          githubToken: ${{ secrets.GITHUB_TOKEN }}

The GITHUB_TOKEN secret is automatically generated by GitHub. This automatic token is scoped only to the repository that is currently running the action.. What this means is that by default the Action cannot update pull requests initiated from forked repositories.

Configuration

By default image actions will compress images so that they’re smaller and will leave your assets looking clear and crisp. If you want to change those defaults, read on.

Previous versions of image-actions used .github/calibre/image-actions.yml for configuration. We suggest that you migrate to the newest configuration format by reading the migration steps below.

Image quality settings

Set custom configuration by adding arguments to the action workflow definition:

- name: Compress Images
  uses: calibreapp/image-actions@master
  with:
    githubToken: ${{ secrets.GITHUB_TOKEN }}
    jpegQuality: '80'
    jpegProgressive: false
    pngQuality: '80'
    webpQuality: '80'
    ignorePaths: 'node_modules/**,build'
    compressOnly: false

Options:

jpegQuality: Number, integer 1-100, default 80 stored in a string
pngQuality: Number, integer 1-100, default 80 stored in a string
webpQuality: Number, integer 1-100, default 80 stored in a string
jpegProgressive: Boolean, true or false, default false
ignorePaths: a comma separated string with globbing support of paths to ignore when looking for images to compress
compressOnly: Boolean, true or false, default false

Running just the compression

By default image-actions will add updated images to the current pull request. It is also possible to set the compressOnly option to true to skip the commit, if you want to handle this separately - including for forks - see below.

- name: Compress Images
  uses: calibreapp/image-actions@master
  with:
    githubToken: ${{ secrets.GITHUB_TOKEN }}
    compressOnly: true

Handling pull requests from forked repos

GitHub actions, by default, do not have permission to alter forked repositories. This means this action, by default, only works for pull requests from branches in the same repository as the destination branch.

You can replace the default GITHUB_TOKEN with a personal access token (PAT) which does have permission for forked repositaries, but this introduces other security considerations (which is why it not available by default).

Alternatively you can run this action only for Pull Requests for the current repo, which is advised when not using PATs to avoid wasting time and compute for compressions that will not be committed using the following syntax (as shown in the example yml files in this README):

    if: github.event.pull_request.head.repo.full_name == github.repository

It is also possible to run an additional instance of this action in compressOnly mode on pushes to master, and then raise a new pull request for any images committed without being compressed (e.g. from a forked repository pull request). This is shown in the below example which uses the create-pull-request action by @peter-evans to open the new Pull Request (note this only raises a Pull Request if any files are actually changed in previous steps).

name: Compress Images on Push to Master
on:
  push:
    branches:
      - master
jobs:
  build:
    name: calibreapp/image-actions
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@master
      - name: Compress Images
        id: calibre
        uses: calibreapp/image-actions@master
        with:
          githubToken: ${{ secrets.GITHUB_TOKEN }}
          compressOnly: true
      - name: Create New Pull Request If Needed
        uses: peter-evans/create-pull-request@master
        with:
          title: Compressed Images
          branch-suffix: timestamp
          commit-message: Compressed Images
          body: ${{ steps.calibre.outputs.markdown }}

Compressing images on a schedule

It is also possible to run image-actions on a recurring schedule. By using the compressOnly option, in conjunction with create-pull-request action by @peter-evans, a new Pull Request will be raised if there are optimised images in a repository.

name: Compress images at 11pm and open a pull request
on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron: '* 23 * * *'
jobs:
  build:
    name: calibreapp/image-actions
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@master
      - name: Compress Images
        id: calibre
        uses: calibreapp/image-actions@master
        with:
          githubToken: ${{ secrets.GITHUB_TOKEN }}
          compressOnly: true
      - name: Create New Pull Request If Needed
        uses: peter-evans/create-pull-request@master
        with:
          title: Compressed Images Nightly
          branch-suffix: timestamp
          commit-message: Compressed Images
          body: ${{ steps.calibre.outputs.markdown }}

Migrate legacy configuration

uses: docker://calibreapp/github-image-actions

If your calibreapp-image-actions.yml file has a reference to docker:// or GITHUB_TOKEN as follows:

- name: calibreapp/image-actions
   uses: docker://calibreapp/github-image-actions
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Update your configuration to:

- name: Compress Images
  uses: calibreapp/image-actions@master
  with:
    githubToken: ${{ secrets.GITHUB_TOKEN }}

.github/calibre/image-actions.yml

If your repository uses .github/calibre/image-actions.yml for configuration, it should be moved into .github/workflows/calibreapp-image-actions.yml. Then delete the image-actions.yml file.

ignorePaths is no longer an array and is now a comma separated list. eg: ignorePaths: "node_modules/**,bin"

Local Development

Install dependencies: npm install
Build project: npm run build or npm run watch for continuous rebuild-on-save
Run tests npm run test
Confirm a successful Docker build: docker build -t calibreapp/image-actions:dev .

tunetheweb / image-actions

Image Actions

Table of Contents