PackSquash-action

Action to run PackSquash, a Minecraft resource and data pack optimizer, in a GitHub Actions workflow, which allows it to better integrate in continuous integration processes.

⚙️ Usage examples

This section contains some example GitHub Actions workflow files that leverage this action to achieve typical continuous integration tasks.

The action accepts many input parameters under the with key. Most are optional, but you might want to set them to customize the behavior of the action. These examples cover only the most salient parameters, so head over to the input parameters section if you want to know more about them.

Optimize each commit to an artifact

This workflow will execute PackSquash for each push to the repository, generating an artifact with the optimized pack for each change. The workflow expects the pack to be in the repository root. The generated artifact can be downloaded by users with read access to the repository via the GitHub web UI or CLI. It can also be downloaded in other steps or workflows using the actions/download-artifact action.

File tree

Repository root
├── .github
│   └── workflows
│       └── packsquash.yml
├── assets
│   └── ...
└── pack.mcmeta

Workflow file: .github/workflows/packsquash.yml

name: Optimize resource pack
on: [push]
jobs:
  packsquash:
    name: Optimize resource pack
    runs-on: ubuntu-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # A non-shallow repository clone is required
      - name: Run PackSquash
        uses: ComunidadAylas/PackSquash-action@v4
        with:
          packsquash_version: latest # Uses the latest PackSquash release supported by the action

Optimize each commit to an artifact, but changing the pack directory

In some cases, the directory where the pack is located is not the same as repository root. You can specify a directory other than the repository root by changing the options input parameter, which can be a path to a TOML file or an inline TOML string containing the options to pass to the PackSquash command-line application. These options follow the same format as the options files used by the PackSquash application, which are documented here.

Changing the pack directory is handy for repositories that contain multiple packs, or for isolating the pack from the rest of the repository to prevent miscellaneous files from being considered as pack files by PackSquash.

File tree

Repository root
├── .github
│   └── workflows
│       └── packsquash.yml
└── pack
    ├── assets
    │   └── ...
    └── pack.mcmeta

Workflow file: .github/workflows/packsquash.yml

name: Optimize resource pack
on: [push]
jobs:
  packsquash:
    name: Optimize resource pack
    runs-on: ubuntu-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # A non-shallow repository clone is required
      - name: Run PackSquash
        uses: ComunidadAylas/PackSquash-action@v4
        with:
          # When changing the options passed to PackSquash, it may be a good idea to lock
          # your workflow to a specific PackSquash version instead of "latest". This will
          # prevent sudden failures when releases that introduce incompatible changes to
          # the options file format are made, but will require you to manually update
          # the PackSquash version your workflows use when a release occurs
          packsquash_version: latest
          options: |
            pack_directory = 'pack'

Optimize to an artifact and create a release

The previous examples can easily be expanded to create releases automatically by downloading the generated artifact and uploading it again as a release.

Workflow file (every push): .github/workflows/packsquash.yml

This workflow creates a new tag and release named action-v{number} for every push event, which is triggered by commits and other tags.

name: Optimize resource pack
on: [push]
# This permissions section explicitly gives the workflow permission to create releases.
# Most of the time it's not needed to set it, as the default GITHUB_TOKEN permissions
# are permissive enough, but that's not always the case
permissions:
  contents: write
jobs:
  packsquash:
    name: Optimize resource pack
    runs-on: ubuntu-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # A non-shallow repository clone is required
      - name: Run PackSquash
        uses: ComunidadAylas/PackSquash-action@v4
        with:
          packsquash_version: latest
          options: |
            # Optimize the pack in the root repository directory.
            # This is the default value for pack_directory when no PackSquash options are defined
            pack_directory = '.'

            # Set a custom output file path to work with the generated ZIP file
            # without needing to download its artifact in a separate step
            output_file_path = '/tmp/pack.zip'
      - name: Tag and create release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: action-v${{ github.run_number }}
          files: /tmp/pack.zip

Workflow file (every tag push): .github/workflows/packsquash.yml

This workflow creates a new release whenever a tag is pushed. The release will have the same name as the tag.

name: Optimize resource pack
on:
  push:
    tags:
      - '**'
jobs:
  packsquash:
    name: Optimize resource pack
    runs-on: ubuntu-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # A non-shallow repository clone is required
      - name: Run PackSquash
        uses: ComunidadAylas/PackSquash-action@v4
        with:
          packsquash_version: latest
          options: |
            pack_directory = '.'
            output_file_path = '/tmp/pack.zip'
      - name: Create release
        uses: softprops/action-gh-release@v2
        with:
          files: /tmp/pack.zip

Advanced: automatic release deployment via SSH

When developing in private repositories it is not possible for vanilla Minecraft clients to download resource packs from release artifacts, as they lack the required authentication credentials. A common solution is to upload releases to an external web server directly from a GitHub Actions workflow via SSH.

Warning: keep in mind that just uploading files to the web server might not be enough to make players download the new version the next time they connect. The Minecraft server should be configured with the appropriate resource pack ZIP file URL and hash each time the pack is updated. Otherwise, clients will receive stale information and may decide to use the copy they have downloaded already. This example omits that part on purpose because the precise way of doing it (running plugin commands via RCON, modifying the server.properties file and restarting the server, etc.) is environment-specific.

Secrets

This example workflow uses the following secrets, which can be set in the repository settings.

Name	Description
SSH_HOST	Web (and/or SSH) server host name or address
SSH_USERNAME	Username for SSH authentication
SSH_PRIVATE_KEY	Private key for SSH authentication
SSH_PORT	SSH server listen port
DEPLOY_DIRECTORY	Directory where the pack will be deployed to. Usually /var/www/ for the web server root

Workflow file: .github/workflows/deploy.yml

name: Deploy via SSH
on: [workflow_dispatch]
jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - name: Download latest released pack
        uses: dsaltares/fetch-gh-release-asset@1.1.2
        with:
          file: pack.zip
          target: pack.zip
      - name: Rename pack file
        # An unique name guarantees an unique URL. Different URLs
        # compel Minecraft clients to download packs again, but
        # make sure to read and understand the warning above before
        # doing this in production!
        run: mv pack.zip pack-${{ github.run_number }}.zip
      - name: Deploy pack file
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USERNAME }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          port: ${{ secrets.SSH_PORT }}
          source: pack-${{ github.run_number }}.zip
          target: ${{ secrets.DEPLOY_DIRECTORY }}

📄 Template repositories

Some users are creating template repositories with this action, making it very easy to get up and running with the development of your very own pack. We have curated a list of handy repository templates below, but feel free to send pull requests to add new reusable templates here!

• osfanbuff63/minecraft-datapack: a template repository for vanilla Minecraft data packs that uses PackSquash to bundle them in optimized ZIP files. Each commit is optimized to a ZIP artifact. No releases or deployments are made.
• sya-ri/MinecraftResourcePackTemplate (in Japanese; uses outdated versions of PackSquash and this action): a template repository for Minecraft resource packs that uses PackSquash to bundle them in optimized ZIP files. Each commit is optimized to a ZIP artifact, and a release is made when a new tag is pushed.

📝 Input parameters

The input parameters accepted by the action are documented below.

Basic parameters

These parameters enable essential tuning of the options passed to PackSquash and the behavior of the action.

packsquash_version

Default value

None (required)

Description

The PackSquash version that the action will use. Please note that too old or too new versions may be incompatible or fully supported by the action. There are four types of versions that can be specified:

• vXXX, where XXX is a PackSquash release version, such as 0.4.0 or 0.3.1.
• latest, which refers to the latest PackSquash release version. This version will change over time as new PackSquash releases are published. Different PackSquash version may use distinct options, so if you use custom options it may be necessary to change them when new PackSquash releases come out.
• latest-unstable, which refers to the latest unstable PackSquash build, automatically generated by CI from the source code on the master branch in the PackSquash repository. As with latest, please note that this version varies over time.
• The full SHA hash of a commit on the master branch of the PackSquash repository. This references the unstable build generated by CI for the specified source code commit. Please bear in mind that GitHub retains unstable build artifacts for a limited time, so too old commits may no longer have their associated build available.

options

Default value

pack_directory = "."

Description

The options to pass to PackSquash, either as a file path or as a TOML string. Relative paths are interpreted from the repository root. If not specified, PackSquash will optimize a pack in the repository root with the default options.

token

Default value

${{ github.token }}

Description

The GitHub API authentication token that will be used for operations that may require authentication. Documentation about the default token is available here. By default, the GitHub-generated GITHUB_TOKEN secret is used, which is suitable for use in most scenarios, including private repositories.

artifact_name

Default value

Optimized pack

Description

The name of the workflow artifact containing the generated ZIP file that the action will upload. Later steps in the workflow will be able to download it by this name. Changing this may be needed in complex workflows, where the action runs several times.

show_emoji_in_packsquash_logs

Default value

true

Description

If true, the action will instruct PackSquash to use emojis in the logs it generates, which look prettier. Otherwise, plain ASCII decoration characters will be used instead.

enable_color_in_packsquash_logs

Default value

true

Description

If true, the action will instruct PackSquash to color the log messages it generates, which looks prettier. Otherwise, the messages will not be colored.

Advanced action parameters

This action also supports additional parameters that might be useful for more specific use cases. It shouldn't be necessary to set them for most circumstances, though.

system_id

Default value

Automatically generated

Description

The system identifier PackSquash will use to generate cryptographic secrets. Unless you know what you are doing, it is recommended to leave this parameter unset, as doing so will let the action generate and use a suitable system identifier automatically.

action_cache_revision

Default value

​ (empty string)

Description

The revision of the cache the action uses internally. You should only need to change this revision if you want the action to not reuse any cached information, like the system identifier, or want to isolate jobs from each other due to undesired interferences between them. This will render any previously generated ZIP file unusable for speed optimizations unless you manage system_id yourself.

🔒 Security

This action may store in a cache the encryption key needed to read file modification times from the ZIP files PackSquash generates. Therefore, such encryption key can be exposed to anyone that has access to the repository. However, this is not a concern in practical scenarios, because the file modification times are generated from the commit history, so having access to the repository already provides this information. If for some reason you do not want this behavior, you can set never_store_squash_times to true, although that will likely slow down PackSquash. For more information about the implications of caching potentially-sensitive data, please read the GitHub documentation.

✉️ Contact and support

Please check out the PackSquash repository for contact information.

🧑‍🤝‍🧑 Contributors

Thanks goes to these wonderful people (emoji key):

sya-ri 🐛 💻 🖋 🔣 📖 💡 🤔 🚇 💬 🔬

Alejandro González 💻 🖋 📖 🤔 🚇 🚧 💬 🔬 👀

Miku 🐛 🤔

osfanbuff63 🤔 💡

alumina6767 📝 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!