{"id":13454590,"url":"https://github.com/calibreapp/image-actions","last_synced_at":"2025-05-14T01:08:24.554Z","repository":{"id":38361951,"uuid":"181617728","full_name":"calibreapp/image-actions","owner":"calibreapp","description":"A Github Action that automatically compresses JPEGs, PNGs and WebPs in Pull Requests.","archived":false,"fork":false,"pushed_at":"2025-05-01T22:34:10.000Z","size":3336,"stargazers_count":1456,"open_issues_count":40,"forks_count":67,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-05-10T21:46:30.447Z","etag":null,"topics":["compression","github-action","github-actions","image-compression","image-processing","performance","performance-monitoring","performance-testing"],"latest_commit_sha":null,"homepage":"https://calibreapp.com/blog/compress-images-in-prs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/calibreapp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-16T05:00:42.000Z","updated_at":"2025-05-09T16:58:40.000Z","dependencies_parsed_at":"2024-03-31T13:27:38.796Z","dependency_job_id":"35eff2c5-5f72-407f-81b5-1b71dc8082ae","html_url":"https://github.com/calibreapp/image-actions","commit_stats":{"total_commits":276,"total_committers":19,"mean_commits":"14.526315789473685","dds":0.4311594202898551,"last_synced_commit":"80b3ba2b30cc4d1935d24959841821cf324f23ab"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calibreapp%2Fimage-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calibreapp%2Fimage-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calibreapp%2Fimage-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calibreapp%2Fimage-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/calibreapp","download_url":"https://codeload.github.com/calibreapp/image-actions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253486837,"owners_count":21916142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compression","github-action","github-actions","image-compression","image-processing","performance","performance-monitoring","performance-testing"],"created_at":"2024-07-31T08:00:55.641Z","updated_at":"2025-05-14T01:08:19.545Z","avatar_url":"https://github.com/calibreapp.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","JavaScript","🛠️ Developer Tools"],"sub_categories":[],"readme":"# Calibre Image Actions\r\n\r\n[![NPM package](https://img.shields.io/npm/v/react-live-chat-loader?color=informational)](https://www.npmjs.com/package/react-live-chat-loader)\r\n[![License](https://img.shields.io/github/license/calibreapp/image-actions?color=informational)](https://github.com/calibreapp/react-live-chat-loader/blob/main/LICENSE)\r\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-success)](CODE_OF_CONDUCT.md)\r\n[![Contribution guidelines](https://img.shields.io/badge/PRs-welcome-success)](CONTRIBUTING.md)\r\n\r\nImage Actions is a Github Action built by performance experts at [Calibre](https://calibreapp.com/) that automatically compresses JPEGs, PNGs and WebPs in Pull Requests.\r\n\r\nImage Actions offers:\r\n\r\n- **Fast, efficient and near-lossless compression**\r\n- Best image compression algorithms available ([libvips](https://github.com/libvips/libvips))\r\n- [Ease of customisation](#Configuration): use default settings or adapt to your needs\r\n- Running on demand or schedule\r\n- Supports GitHub Enterprise\r\n\r\n...and more! \r\n\r\n## 🖇 Table of Contents\r\n\r\n1. [Usage](#-usage)\r\n2. [Configuration](#%EF%B8%8F-configuration)\r\n3. [Migrating legacy configuration](#%EF%B8%8F-migrating-legacy-configuration)\r\n4. [Contributing](#-contributing)\r\n5. [Resources](#-resources)\r\n6. [License](#-license)\r\n\r\n## 🛠 Usage\r\n\r\n1. Create a `.github/workflows/calibreapp-image-actions.yml` file in your repository with the following configuration:\r\n\r\n```yml\r\nname: Compress Images\r\non:\r\n  pull_request:\r\n    # Run Image Actions when JPG, JPEG, PNG or WebP files are added or changed.\r\n    # See https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpushpull_requestpaths for reference.\r\n    paths:\r\n      - '**.jpg'\r\n      - '**.jpeg'\r\n      - '**.png'\r\n      - '**.webp'\r\njobs:\r\n  build:\r\n    # Only run on Pull Requests within the same repository, and not from forks.\r\n    if: github.event.pull_request.head.repo.full_name == github.repository\r\n    name: calibreapp/image-actions\r\n    permissions: write-all\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - name: Checkout Repo\r\n        uses: actions/checkout@v4\r\n\r\n      - name: Compress Images\r\n        uses: calibreapp/image-actions@main\r\n        with:\r\n          # The `GITHUB_TOKEN` is automatically generated by GitHub and scoped only to the repository that is currently running the action. By default, the action can’t update Pull Requests initiated from forked repositories.\r\n          # See https://docs.github.com/en/actions/reference/authentication-in-a-workflow and https://help.github.com/en/articles/virtual-environments-for-github-actions#token-permissions\r\n          githubToken: ${{ secrets.GITHUB_TOKEN }}\r\n```\r\n\r\n2. Open a Pull Request with added or changed imagery. Image Actions will process the files and post a comment, like so:\r\n\r\n![Calibre Image Actions Preview](images/image-actions-preview.png)\r\n\r\n3. Merge your Pull Request and enjoy lighter images or explore what’s possible further with [configuration options](#configuration). 👇🏻\r\n\r\n## ⚙️ Configuration\r\n\r\nBy 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 or expand those defaults, read on for available options.\r\n\r\n:warning: If you are using an older version of Image Actions referencing `.github/calibre/image-actions.yml`, we suggest you [migrate to the latest configuration format](#migrate-legacy-configuration).\r\n\r\n### Control image quality settings\r\n\r\nAdd the following arguments to the workflow definition to control compression settings:\r\n\r\n```yml\r\nwith:\r\n  jpegQuality: '80'\r\n  jpegProgressive: false\r\n  pngQuality: '80'\r\n  webpQuality: '80'\r\n```\r\n\r\n**Options:**\r\n\r\n- [jpegQuality](http://sharp.pixelplumbing.com/en/stable/api-output/#jpeg): Number, integer 1-100, default 80 stored in a string.\r\n- [jpegProgressive](http://sharp.pixelplumbing.com/en/stable/api-output/#jpeg): Boolean, true or false, default false.\r\n- [pngQuality](http://sharp.pixelplumbing.com/en/stable/api-output/#png): Number, integer 1-100, default 80 stored in a string.\r\n- [webpQuality](http://sharp.pixelplumbing.com/en/stable/api-output/#webp): Number, integer 1-100, default 80 stored in a string.\r\n\r\n### Ignore paths\r\n\r\nAdd the following argument to the workflow definition to ignore selected paths:\r\n\r\n```yml\r\nwith:\r\n  ignorePaths: 'node_modules/**,build'\r\n```\r\n\r\n`ignorePaths` accepts a comma-separated string with [globbing](https://www.npmjs.com/package/glob) support of paths to ignore when looking for images to compress.\r\n\r\n### Run compression only\r\n\r\nBy default, Image Actions adds optimised images to the current Pull Request and posts a summary comment.\r\n\r\nUse the `compressOnly` option with `true` value to skip the commit and summary comment if you want to handle this separately (including for forks):\r\n\r\n```yml\r\nwith:\r\n  compressOnly: true\r\n```\r\n\r\n`compressOnly` accepts a Boolean value (true or false) and defaults to false.\r\n\r\n### Compress on demand or on schedule\r\n\r\nIt is also possible to run Image Actions [on demand](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/) or on a [recurring schedule](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule). By using the `compressOnly` option, in conjunction with [`create-pull-request`](https://github.com/peter-evans/create-pull-request) action by [@peter-evans](https://github.com/peter-evans), a new Pull Request will be raised if there are optimised images in a repository.\r\n\r\nSee an example below:\r\n\r\n```yml\r\n# Compress images on demand (workflow_dispatch), and at 11pm every Sunday (schedule).\r\n# Open a Pull Request if any images can be compressed.\r\nname: Compress Images\r\non:\r\n  workflow_dispatch:\r\n  schedule:\r\n    - cron: '00 23 * * 0'\r\njobs:\r\n  build:\r\n    name: calibreapp/image-actions\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - name: Checkout Repo\r\n        uses: actions/checkout@v3\r\n      - name: Compress Images\r\n        id: calibre\r\n        uses: calibreapp/image-actions@main\r\n        with:\r\n          githubToken: ${{ secrets.GITHUB_TOKEN }}\r\n          compressOnly: true\r\n      - name: Create New Pull Request If Needed\r\n        if: steps.calibre.outputs.markdown != ''\r\n        uses: peter-evans/create-pull-request@v4\r\n        with:\r\n          title: Compressed Images Nightly\r\n          branch-suffix: timestamp\r\n          commit-message: Compressed Images\r\n          body: ${{ steps.calibre.outputs.markdown }}\r\n```\r\n\r\n### Process Pull Requests from forked repositories\r\n\r\nBy default, GitHub Actions do not have permission to alter forked repositories. For this reason, Image Actions only works for Pull Requests from branches in the same repository as the destination branch. There are several workarounds for this limitation:\r\n\r\n1. **Replace the default `GITHUB_TOKEN` with a [Personal Access Token (PAT)](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#permissions-for-the-github_token) which does have permission to access forked repositories.** Be aware that this introduces potential security concerns (which is why it not available by default).\r\n\r\n2. **Run Image Actions only for Pull Requests in the current repository.** This approach is advised when not using Personal Access Tokens (PATs) to avoid wasting time and compute for compressions that will not be committed. Use the following configuration to check if a Pull Request belongs to the repository:\r\n\r\n```yml\r\nif: github.event.pull_request.head.repo.full_name == github.repository\r\n```\r\n\r\n3. **Run an additional instance of Image Actions in `compressOnly` mode on pushes to `main`, and then raise a new Pull Request for any images committed without being compressed (e.g. from a forked repository PR).** See the configuration in the below example which uses the [create-pull-request](https://github.com/peter-evans/create-pull-request) action by [@peter-evans](https://github.com/peter-evans) to open the new Pull Request (this only raises a Pull Request if any files are changed in previous steps).\r\n\r\n```yml\r\nname: Compress Images on Push to main branch\r\non:\r\n  push:\r\n    branches:\r\n      - main\r\n    paths:\r\n      - '**.jpg'\r\n      - '**.jpeg'\r\n      - '**.png'\r\n      - '**.webp'\r\njobs:\r\n  build:\r\n    name: calibreapp/image-actions\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - name: Checkout Repo\r\n        uses: actions/checkout@v3\r\n      - name: Compress Images\r\n        id: calibre\r\n        uses: calibreapp/image-actions@main\r\n        with:\r\n          githubToken: ${{ secrets.GITHUB_TOKEN }}\r\n          compressOnly: true\r\n      - name: Create New Pull Request If Needed\r\n        if: steps.calibre.outputs.markdown != ''\r\n        uses: peter-evans/create-pull-request@v4\r\n        with:\r\n          title: Compressed Images\r\n          branch-suffix: timestamp\r\n          commit-message: Compressed Images\r\n          body: ${{ steps.calibre.outputs.markdown }}\r\n```\r\n\r\n### Combined workflow\r\n\r\nYou can combine all of the above customisation options into one all-encompassing workflow to avoid having to set up separate workflows with a lot of duplication.\r\n\r\nThe example below ensures the right order of task execution within Image Actions. If you’d like to reuse it, make sure to change `example/example_repo` to your repository details.\r\n\r\n```yml\r\n# Image Actions will run in the following scenarios:\r\n# - on Pull Requests containing images (not including forks)\r\n# - on pushing of images to `main` (for forks)\r\n# - on demand (https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/)\r\n# - at 11 PM every Sunday in anything gets missed with any of the above scenarios\r\n# For Pull Requests, the images are added to the PR.\r\n# For other scenarios, a new PR will be opened if any images are compressed.\r\nname: Compress images\r\non:\r\n  pull_request:\r\n    paths:\r\n      - '**.jpg'\r\n      - '**.jpeg'\r\n      - '**.png'\r\n      - '**.webp'\r\n  push:\r\n    branches:\r\n      - main\r\n    paths:\r\n      - '**.jpg'\r\n      - '**.jpeg'\r\n      - '**.png'\r\n      - '**.webp'\r\n  workflow_dispatch:\r\n  schedule:\r\n    - cron: '00 23 * * 0'\r\njobs:\r\n  build:\r\n    name: calibreapp/image-actions\r\n    runs-on: ubuntu-latest\r\n    # Only run on main repo on and PRs that match the main repo.\r\n    if: |\r\n      github.repository == 'example/example_repo' \u0026\u0026\r\n      (github.event_name != 'pull_request' ||\r\n       github.event.pull_request.head.repo.full_name == github.repository)\r\n    steps:\r\n      - name: Checkout Branch\r\n        uses: actions/checkout@v3\r\n      - name: Compress Images\r\n        id: calibre\r\n        uses: calibreapp/image-actions@main\r\n        with:\r\n          githubToken: ${{ secrets.GITHUB_TOKEN }}\r\n          # For non-Pull Requests, run in compressOnly mode and we'll PR after.\r\n          compressOnly: ${{ github.event_name != 'pull_request' }}\r\n      - name: Create Pull Request\r\n        # If it's not a Pull Request then commit any changes as a new PR.\r\n        if: |\r\n          github.event_name != 'pull_request' \u0026\u0026\r\n          steps.calibre.outputs.markdown != ''\r\n        uses: peter-evans/create-pull-request@v4\r\n        with:\r\n          title: Auto Compress Images\r\n          branch-suffix: timestamp\r\n          commit-message: Compress Images\r\n          body: ${{ steps.calibre.outputs.markdown }}\r\n```\r\n\r\n## ♻️ Migrating legacy configuration\r\n\r\nIf you are using an older version of Image Actions, we recommend checking that your settings are up-to-date.\r\n\r\n### Uses and `GITHUB_TOKEN` definition\r\n\r\nIf your `calibreapp-image-actions.yml` file has a reference to `docker://` or `GITHUB_TOKEN` as follows:\r\n\r\n```yml\r\n- name: calibreapp/image-actions\r\n    uses: docker://calibreapp/github-image-actions\r\n    env:\r\n      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\r\n```\r\n\r\nUpdate your configuration to:\r\n\r\n```yml\r\n- name: Compress Images\r\n  uses: calibreapp/image-actions@main\r\n  with:\r\n    githubToken: ${{ secrets.GITHUB_TOKEN }}\r\n```\r\n\r\n### Location and name of the configuration file\r\n\r\nIf 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.\r\n\r\n### Listing `ignorePaths`\r\n\r\n`ignorePaths` is no longer an array and is now a comma separated list. E.g. `ignorePaths: \"node_modules/**,bin\"`.\r\n\r\n## 🙌🏻 Contributing\r\n\r\nHappy to hear you’re interested in contributing to Image Actions! Please find our contribution guidelines [here](CONTRIBUTING.md).\r\n\r\n## 📚 Resources\r\n\r\n#### Related reading:\r\n\r\n- [Automatically compress images on Pull Requests](https://calibreapp.com/blog/compress-images-in-prs/)\r\n- [Optimize Images with a GitHub Action](https://css-tricks.com/optimize-images-with-a-github-action/)\r\n- [Image Actions on GitHub Marketplace](https://github.com/marketplace/actions/image-actions)\r\n- [Start monitoring and improving your performance](https://calibreapp.com/)\r\n\r\n#### Image compression tools:\r\n\r\n- [sharp](https://github.com/lovell/sharp)\r\n- [libvips](https://github.com/libvips/libvips)\r\n\r\n## 💼 License\r\n\r\nThis project is licensed under a [GNU General Public License](LICENSE).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalibreapp%2Fimage-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcalibreapp%2Fimage-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalibreapp%2Fimage-actions/lists"}