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.
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.
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.
Repository root
├── .github
│ └── workflows
│ └── packsquash.yml
├── assets
│ └── ...
└── pack.mcmeta
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 actionIn 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.
Repository root
├── .github
│ └── workflows
│ └── packsquash.yml
└── pack
├── assets
│ └── ...
└── pack.mcmeta
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'The previous examples can easily be expanded to create releases automatically by downloading the generated artifact and uploading it again as a release.
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.zipThis 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.zipWhen 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.
Important
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.
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 |
Tip
To enhance security, consider not disabling SSH host key verification with
the -o 'StrictHostKeyChecking=no' option used in the workflow file below.
Instead, you can add SSHFP records with the expected host key to its DNS host
name. When using a DNSSEC-aware resolver with DNSSEC-protected SSHFP records
in place, the -o 'VerifyHostKeyDNS=yes' SSH client option is enough to
automatically and securely authenticate the host key. GitHub-hosted runners
have been experimentally confirmed to use a DNSSEC-aware resolver that works
well for SSHFP record validation.
Another similarly secure but simpler to set up approach involves adding the
expected host key beforehand to the /etc/ssh/ssh_known_hosts or
~/.ssh/known_hosts file. However, this method leads to a decentralization of
the locations where the host key needs to be stored, which may be less
scalable and maintainable. The format for these files is documented
here.
Further reading:
name: Deploy via SSH
on: [workflow_dispatch]
jobs:
deploy:
name: Deploy
runs-on: ubuntu-latest
steps:
- name: Download latest released pack
uses: dsaltares/[email protected]
with:
file: pack.zip
target: pack.zip
# An unique name guarantees an unique URL. Different URLs
# compel Minecraft clients to download packs again, but
# make sure to read and understand the note above before
# doing this in production!
- name: Deploy pack file
run: |
echo '${{ secrets.SSH_PRIVATE_KEY }}' > ~/.ssh/id_rsa
chmod 600 ~/.ssh/id_rsa
scp -P ${{ secrets.SSH_PORT }} \
-o 'StrictHostKeyChecking=no' \
pack.zip \
${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }}:${{ secrets.DEPLOY_DIRECTORY }}/pack-${{ github.run_number }}.zipSome 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.
The input parameters accepted by the action are documented below.
These parameters enable essential tuning of the options passed to PackSquash and the behavior of the action.
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 with or not fully supported by the action. There are four types of versions that can be specified:
vXXX, whereXXXis a PackSquash release version, such as0.4.0or0.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 themasterbranch in the PackSquash repository. As withlatest, please note that this version varies over time.- The full SHA hash of a commit on the
masterbranch 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Please check out the PackSquash repository for contact information.
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!
