feat: Add Github action artifact download support by harrisonablack · Pull Request #816 · itzg/mc-image-helper

harrisonablack · 2026-07-16T04:07:46Z

Add sub-command under GithubCommands.java to allow downloading of specific Github action artifacts

refs: #810

- required flags - Pattern type for Name pattern - Unzip default false - RunSelector static class - GithubCommand parent

Changed name-pattern to artifact-pattern

harrisonablack · 2026-07-17T05:03:37Z

@itzg @SgtMate

You can either pass a specific workflow run id, or a workflow name, along with organisation/repository.

Command then queries actions, selecting either the latest succesful action for a specific workflow, or the already provided workflow id. Then pattern matches against artifacts and downloads the matching artifact.

Usage: mc-image-helper github download-artifact [-h] [--overwrite] [--unzip]
       --artifact-pattern=<artifactPattern> [-o=<outputDirectory>]
       (--workflow=ID|FILE | --run-id=ID) [[--use-http2] [--wiretap]] org/repo
Download an artifact from a successful GitHub Actions workflow
      org/repo
      --artifact-pattern=<artifactPattern>
                           Regular expression that must match exactly one
                             artifact name
  -h, --help
  -o, --output-directory=<outputDirectory>
                           Output directory of downloaded artifact
      --overwrite          Overwrite existing files when extracing zip
      --run-id=ID          Query this specific workflow run to download an
                             artifact
      --unzip              Extract the downloaded artifact
      --use-http2          Whether to use HTTP/2.
                           Default: true
                           Env: FETCH_USE_HTTP2
      --wiretap            Whether to enable Reactor Netty wiretap logging.
                             Make sure to set logging level to trace.
                           Default: false
                           Env: FETCH_WIRETAP
      --workflow=ID|FILE   Query this workflow for the latest successful run to
                             download an artifact

For example, with @SgtMate use case, the below queries the latest successful daily build, downloading the Java17 server arifact, and extracting it to ./gtnh

GH_TOKEN="$(gh auth token)" ./gradlew run --args="github download-artifact --workflow daily-modpack-build.yml --name-pattern='GTNH-daily-\d{4}-\d{2}-\d{2}\+\d+-server-java17-25\.zip' -o=./gtnh --unzip GTNewHorizons/DreamAssemblerXXL"

Github requires a token to be passed when downloading Artifacts
https://docs.github.com/en/rest/actions/artifacts?apiVersion=2026-03-10

SgtMate · 2026-07-17T11:27:26Z

this looks great! this is exactly what i need. one thing i want to add tho is the --output-filename option (from the get command)

harrisonablack · 2026-07-17T11:38:27Z

this looks great! this is exactly what i need. one thing i want to add tho is the --output-filename option (from the get command)

When you want to change output name, do you want the file still as a zip i assume? And the zip renamed? Or whatever format the Artifact is

SgtMate · 2026-07-17T12:09:08Z

So what I need is for the command to return the filename that was downloaded. (independent of if its unpacked or not).
--output-filename Output the resulting filename

itzg · 2026-07-17T12:24:05Z

This looks great @harrisonablack and I like @SgtMate 's request.

SgtMate · 2026-07-17T12:52:41Z

another question, just so i understand. is it correct, that the gh token is not handed to the command directly? so i need to set it in env?

itzg · 2026-07-17T12:56:17Z

The token can be passed either way:

    @Option(names = "--token", defaultValue = "${env:GH_TOKEN}",
        description = "An access token for GitHub to elevate rate limit vs anonymous access"
    )

however, within itzg/minecraft-server the expectation is that the user has set the container env var to allow for token access across the whole startup.

SgtMate · 2026-07-17T13:00:00Z

@itzg ok get it, then i will adhere to the existing processes.

itzg · 2026-07-17T13:00:23Z

Wait, that's bit of a usability problem. Users installing GTNH aren't expecting to need a GitHub token.

@harrisonablack are you certain the APIs used need authenticated access?

SgtMate · 2026-07-17T13:01:43Z

@itzg thats fine, I'll cleary state this in the addition to the documentation.

harrisonablack · 2026-07-17T13:21:22Z

Wait, that's bit of a usability problem. Users installing GTNH aren't expecting to need a GitHub token.

@harrisonablack are you certain the APIs used need authenticated access?

Yes, when i remove the null token check, and don't set env, command fails with a 401.

I believe its only the Artifact download endpoint that requires auth

[mc-image-helper] 23:18:25.773 ERROR : 'download-artifact' command failed. Version is ???: FailedRequestException: HTTP request of https://api.github.com/repos/GTNewHorizons/DreamAssemblerXXL/actions/artifacts/8398696458/zip failed with 401 Unauthorized: Trying to retrieve file

./gradlew run --args="github download-artifact --workflow daily-modpack-build.yml --artifact-pattern='GTNH-daily-\d{4}-\d{2}-\d{2}\+\d+-server-java17-25\.zip' -o=./gtnh --unzip GTNewHorizons/DreamAssemblerXXL"

harrisonablack · 2026-07-17T13:28:02Z

https://docs.github.com/en/rest/actions/artifacts?apiVersion=2026-03-10#download-an-artifact

The fine-grained token must have the following permission set:

'Actions' repository permissions (read)

SgtMate · 2026-07-17T13:38:32Z

another thing i need to add to my request is some kind of dry-run functionality. where only the resulting download candidate is returned without downloading it. I need this to check if an update is even required once the container is restarted. Currently im just comparing the old and new filename. This would greatly help in reducing unneeded downloads.

@harrisonablack you think you can implement this with githubs given api?

itzg · 2026-07-17T15:20:34Z

It's almost like it needs a "skip existing" like the get command, but with a 3-way outcome

New file was available, here's its name
Existing file was already present
Something bad happened

harrisonablack · 2026-07-17T16:24:27Z

another thing i need to add to my request is some kind of dry-run functionality. where only the resulting download candidate is returned without downloading it. I need this to check if an update is even required once the container is restarted. Currently im just comparing the old and new filename. This would greatly help in reducing unneeded downloads.

@harrisonablack you think you can implement this with githubs given api?

@SgtMate My thought process is yes, but what are we trying to do? What level of automation of the process do we want to reach?

If you want to automate updating / installing daily builds of GTNH, i would lean towards a manifest similar to Paper, where when the server is installed, a file is created that states which version is installed.

Then when we go to restart the container, we can check for a new build and can compare artifact names / dates before downloading.

If we then automate isntalling / updating, my next questions are then GTNH specific; which files are safe to replace when updating a server, and which files do we need to keep? I'm not overly familiar with Modpacks / Modpack servers.

I would lean more towards implementing a install-gtnh command in mc-image-helper to automate this process.

But i digress, yes, i can add another function / command argument to return the name of the artifact only

harrisonablack · 2026-07-17T16:25:16Z

It's almost like it needs a "skip existing" like the get command, but with a 3-way outcome

New file was available, here's its name

Existing file was already present

Something bad happened

I did add an --overwrite flag, which when set overwrites already existing files during the unzip. Default behaviour is to skip existing files

… exists Previously if the output directory already existed, the log.error would be triggered, however proceces failed to create directory as directory already existed

itzg · 2026-07-17T16:36:56Z

I would lean more towards implementing a install-gtnh command in mc-image-helper to automate this process.

I gently suggested that too 😉

itzg/docker-minecraft-server#4141 (comment)

Seriously though, @SgtMate maybe you could provide some pseudo code or a draft PR to show where the new command fits in and what input/output would be involved in conditions.

harrisonablack · 2026-07-17T16:51:04Z

another thing i need to add to my request is some kind of dry-run functionality. where only the resulting download candidate is returned without downloading it. I need this to check if an update is even required once the container is restarted. Currently im just comparing the old and new filename. This would greatly help in reducing unneeded downloads.

@harrisonablack you think you can implement this with githubs given api?

@SgtMate As well, i'm assuming you want some machine readable format for the output? Or is human readable fine?

I would look at using ResultsFileWriter. The tool gives docker-minecraft-server a list of Enviroment variables to set. We could then create a command, mc-image-helper install-gtnh --check-updates which would return a ResultsFile containing a env var stating the output; GTNH_UPDATES=TRUE or something similar

Previously, if you passed --no-download, the command would exit stating token required, however token isn't required to query the data, only to download

harrisonablack · 2026-07-17T17:06:16Z

@itzg Added two arguments, --print-artifact and --no-download. Currently --print-artifact logs artifact name using a sl4j log

if (printArtifact) {
    log.info("Resolved artifact {}", candidate.block().getName());
}

For example, running

./gradlew run --args="github download-artifact --workflow daily-modpack-build.yml --artifact-pattern='GTNH-daily-\d{4}-\d{2}-\d{2}\+\d+-server-java17-25\.zip' --print-artifact --no-download GTNewHorizons/DreamAssemblerXXL"

returns

[mc-image-helper] 02:58:36.311 INFO  : Resolved artifact GTNH-daily-2026-07-17+628-server-java17-25.zip

Bool checks would error as booleans had null value, providing default false value

itzg · 2026-07-17T17:27:14Z

I would like it to be consistent with https://github.com/itzg/mc-image-helper#get where it's --skip-existing and --output-filename.

For --output-filename it needs to be a System.out.println so scripts can consume the output of the call like:

file=$(mc-image-helper github download-artifact --output-filename ...)

itzg · 2026-07-17T17:27:45Z

...unless @SgtMate you had a different intention with the skipping of download or not.

Changed --print-artifact to --output-filename to maintain consistency, aswell as used System.out.println

harrisonablack · 2026-07-17T17:39:56Z

@itzg

Fixed the print command.

My only concern with --skip-existing is how will it be used and when?

For the GTNH instance, we will always modify the downloaded artifact to use it, unzip it for example. Then its not an easy "does this file already exist?", it comes back to the same thought of "Do we need a manifest"?

Otherwise if the thought of --skip-existing was only, "does this exact file already exist in the output dir?", thats easily implemented and am happy to do so!

itzg · 2026-07-17T17:41:07Z

That'll be for @SgtMate to answer 😄

SgtMate · 2026-07-17T23:37:33Z

oh i see I`ve cause some discussions. Ill try to adress things one by one.

Seriously though, @SgtMate maybe you could provide some pseudo code or a draft PR to show where the new command fits in and what input/output would be involved in conditions.

I simply do a comparison of filenames from the downloaded zip file, if the name matches with the last version installed (stored in a file) the installation is skipped, if it does not match the update is triggered and if the file is missing a fresh install is triggered.

if [[ ! -f /data/.gtnh-version || "$(basename "$gtnh_download_path")" != "$(cat /data/.gtnh-version)" ]]; then

Here gtnh_download_path normaly stores the download location for the download and installation step. After download and install the value $gtnh_download is stored in the file which is derived from the download.

    if ! gtnh_download=$(mc-image-helper github download-artifact --output-filename -o=$base_dir --unzip $gtnh_download_options GTNewHorizons/DreamAssemblerXXL); then
      logError "Failed to download Daily Build for GTNH server files."
      exit 1
    fi

I would lean more towards implementing a install-gtnh command in mc-image-helper to automate this process.

Yes I also see this as the best solution in the longway, but as this results in more complex migration from bash scripts over to java I'd like to split this. also because i think the now requested feature will be helpfull for other contributors of the minecraft server project, I try to have this be as usefull to the overall project as possible even tho I'm focussing on the GTNH implementation.

...unless @SgtMate you had a different intention with the skipping of download or not.

Close, --output-filename is important for me. The thing I need in addition is a way to just get the filename of the zip I would get back to compare to the last installed version before download.

I would like it to be consistent with https://github.com/itzg/mc-image-helper#get where it's --skip-existing and --output-filename.

Agree, this also makes things easier to mainain from the script side same functionality same name.

...unless @SgtMate you had a different intention with the skipping of download or not.

No I dont use skip existing.

I hope i was able to clarify all questions! Thanks for all the work you are putting in! ♥️

harrisonablack · 2026-07-18T13:01:08Z

@itzg

Given that @SgtMate doesn't require --skip-existing, and his needed --output-filename is implemented, is there anything else you want to see changed or added before merge?

itzg · 2026-07-18T13:33:52Z

I'm happy if @SgtMate is happy 😄

I'll proceed with code review from here.

SgtMate · 2026-07-18T14:11:04Z

I think Im happy, if something is still missing Ill adress this in a separate issue. Lets just get things implemented for now and improve incrementally.

itzg

Just some minor things.

Blocks on candidate fetch before command termination

Co-authored-by: Geoff Bourne <itzgeoff@gmail.com>

Remove flux need Co-authored-by: Geoff Bourne <itzgeoff@gmail.com>

…idParameterException

itzg

Thanks!

itzg · 2026-07-20T12:18:22Z

Released in https://github.com/itzg/mc-image-helper/releases/tag/1.63.0

harrisonablack · 2026-07-20T12:54:42Z

Thanks!

All good! Anything else you want me to work on, just mention me in the issue or PR and I'll be there!

harrisonablack added 10 commits July 16, 2026 13:58

feat(githubArtifactDownload): Add DownloadArtifact command signature

1542d18

fix(githubArtifactDownload): Reword command name

cc9671f

fix(githubArtifactDownload): Fix DownloadArtifactCommand signature

149027e

- required flags - Pattern type for Name pattern - Unzip default false - RunSelector static class - GithubCommand parent

feat(githubArtifactDownload): Add Artifact API Models

703d0f5

feat(githubArtifactDownload): Append GithubClient artifact functions

b10ff62

feat(githubArtifactDownload): Append DownloadArtifactCommand arguments

6a1bd5b

feat(githubArtifactDownload): Implement DownloadArtifactCommand

46483f5

fix(githubArtifactDownload): Update picocli command descriptions

b5b8d6d

fix(githubArtifactDownload): Change picocli argument name

88b42fb

Changed name-pattern to artifact-pattern

fix(githubArtifactDownload): Change picocli argument description

18088a0

harrisonablack marked this pull request as ready for review July 17, 2026 05:03

fix(githubArtifactDownload): fix error logging when directory already…

4d8c3c5

… exists Previously if the output directory already existed, the log.error would be triggered, however proceces failed to create directory as directory already existed

fix(githubArtifactDownload): Move token check after early exit

cad80fb

Previously, if you passed --no-download, the command would exit stating token required, however token isn't required to query the data, only to download

fix(githubArtifactDownload): Set picocli argument default value

ae10163

Bool checks would error as booleans had null value, providing default false value

fix(githubArtifactDownload): Fix artifact print name

57a5b4b

Changed --print-artifact to --output-filename to maintain consistency, aswell as used System.out.println

itzg requested changes Jul 19, 2026

View reviewed changes

harrisonablack and others added 10 commits July 20, 2026 15:08

fix(githubArtifactDownload): Move block into doOnNext

2830693

fix(githubArtifactDownload): Block on no download

bd7459d

Blocks on candidate fetch before command termination

fix(githubArtifactDownload): Move block onto newline

df4bee1

Co-authored-by: Geoff Bourne <itzgeoff@gmail.com>

fix(githubArtifactDownload): Get first element

4f46ab4

Remove flux need Co-authored-by: Geoff Bourne <itzgeoff@gmail.com>

fix(githubArtifactDownload): Change thrown error type

42ab954

fix(githubArtifactDownload): Change IllegalArgumentException to Inval…

7d9244c

…idParameterException

fix(githubArtifactDownload): Flatmap token check

12f5cc7

fix(githubArtifactDownload): Change deleteIfExists to delete

64645b1

fix(githubArtifactDownload): Error typo

377c259

fix(githubArtifactDownload): Only print artifact name on picocli option

d1cadc9

harrisonablack requested a review from itzg July 20, 2026 07:30

itzg approved these changes Jul 20, 2026

View reviewed changes

itzg merged commit 2aa1367 into itzg:main Jul 20, 2026
1 check passed

itzg added the enhancement New feature or request label Jul 20, 2026

harrisonablack deleted the feat/githubArtifactDownload branch July 20, 2026 12:54

Uh oh!

Conversation

harrisonablack commented Jul 16, 2026

Uh oh!

harrisonablack commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SgtMate commented Jul 17, 2026

Uh oh!

harrisonablack commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SgtMate commented Jul 17, 2026

Uh oh!

itzg commented Jul 17, 2026

Uh oh!

SgtMate commented Jul 17, 2026

Uh oh!

itzg commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SgtMate commented Jul 17, 2026

Uh oh!

itzg commented Jul 17, 2026

Uh oh!

SgtMate commented Jul 17, 2026

Uh oh!

harrisonablack commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

harrisonablack commented Jul 17, 2026

Uh oh!

SgtMate commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itzg commented Jul 17, 2026

Uh oh!

harrisonablack commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

harrisonablack commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itzg commented Jul 17, 2026

Uh oh!

harrisonablack commented Jul 17, 2026

Uh oh!

harrisonablack commented Jul 17, 2026

Uh oh!

itzg commented Jul 17, 2026

Uh oh!

itzg commented Jul 17, 2026

Uh oh!

harrisonablack commented Jul 17, 2026

Uh oh!

itzg commented Jul 17, 2026

Uh oh!

SgtMate commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

harrisonablack commented Jul 18, 2026

Uh oh!

itzg commented Jul 18, 2026

Uh oh!

SgtMate commented Jul 18, 2026

Uh oh!

itzg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

itzg left a comment

Choose a reason for hiding this comment

Uh oh!

harrisonablack commented Jul 17, 2026 •

edited

Loading

harrisonablack commented Jul 17, 2026 •

edited

Loading

itzg commented Jul 17, 2026 •

edited

Loading

harrisonablack commented Jul 17, 2026 •

edited

Loading

SgtMate commented Jul 17, 2026 •

edited

Loading

harrisonablack commented Jul 17, 2026 •

edited

Loading

harrisonablack commented Jul 17, 2026 •

edited

Loading

SgtMate commented Jul 17, 2026 •

edited

Loading