GitHub publishing

Publish a release on GitHub and it appears on your post by itself. No API keys, no re-uploading.

What it is

GitHub publishing links a GitHub repository to your post. Each time you publish a release on GitHub, a workflow in your repository builds your files and sends them to your post, changelog included.

Why use it

  • No more re-uploading files by hand for every version.
  • Your files get a Built from source mark, so players can see exactly which code they came from.
  • Your GitHub release notes become the changelog.

How it works

  1. Step 1GitHub releaseYou publish a release on GitHub.
  2. Step 2Your workflow runs the ActionIt builds your files and sends them to us.
  3. Step 3We check itWe verify it came from your repository.
  4. Step 4The release appearsAt once for verified creators, after review for everyone else.

There is no key to create or leak. The Action proves which repository and workflow it runs in with the short-lived identity token GitHub gives every run, the same trusted publishing model PyPI and npm use.

Releases from verified creators go live straight away. Releases from everyone else are reviewed every time before they appear.

Set it up

You need a public GitHub repository that builds your files, and a post in a release category such as Mods or Shader Packs. Drafts count.

  1. Step 1: Open your post

    Go to Account, then Posts, choose Edit on your post and open the Releases tab. This works for new and existing posts.

    Go to your posts
  2. Step 2: Choose Link GitHub

    Choose Link GitHub. Under Choose your repository, enter your repository and the workflow file name, then save.

  3. Step 3: Add the step to your workflow

    Copy the step shown under Add the step to your workflow into a workflow that runs when you publish a release.

    Here is a complete workflow for a Gradle mod. Use your post's id, in the address bar of its editor (/post/<id>/edit/), in place of 123.

    YAML
    name: Publish to allminecraft
    on:
      release:
        types: [published]
    
    permissions:
      contents: read
      id-token: write
      attestations: write
    
    jobs:
      publish:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-java@v4
            with:
              distribution: temurin
              java-version: 21
          - run: ./gradlew build
          - uses: allminecraft/publish-action@v1
            with:
              post-id: 123
              files: |
                build/libs/*.jar
                !build/libs/*-sources.jar
                !build/libs/*-dev.jar
    

    Keep the permissions block: id-token: write lets the Action prove which run it is, and attestations: write signs your files. The job must run on a GitHub-hosted runner such as ubuntu-latest.

    Publishing a resource or shader pack? Replace the build steps with run: cd pack && zip -r ../pack.zip . and set files: pack.zip.

  4. Step 4: Publish a release on GitHub

    Publish a release on GitHub. The workflow builds your files and the release appears on your post.

The Built from source mark

This shows where the file came from. It does not mean the code has been reviewed.

The mark proves a file came out of a GitHub-hosted run of a named workflow, at a named commit, in a public repository anyone can read. It was not uploaded by hand or swapped afterwards. It does not vouch for what the code does.

Anyone can check a file themselves with the GitHub CLI:

bash
gh attestation verify my-mod-1.0.0.jar --repo owner/repo

README badges

Show your downloads on your GitHub README with a badge that links back to your post. The count updates by itself. Badges work for any post with releases, linked to GitHub or not.

  • AllMinecraft: 12,480 downloads

    Featured mark

    For the top of a README.

  • AllMinecraft: 12,480 downloads

    Shield

    Sits in a row with other badges.

  • AllMinecraft: 12,480 downloads

    Banner

    A wide download button.

To copy yours, open your post's editor and choose Options → README badges. Pick a style, then copy it as HTML for GitHub or as Markdown. It looks like this:

Markdown
[![AllMinecraft downloads](https://allminecraft.net/badge/123/shield.svg?theme=dark&count=site)](https://allminecraft.net/post/123)

Action inputs

Only post-id and files are needed. The Action sets release-id, release-url and status (approved or pending) as outputs.

InputRequiredDescription
post-idYesYour post's numeric id.
filesYesGlob of the files to publish, 1 to 3 matches. A line starting with ! leaves files out.
primaryNoThe file shown first. Defaults to the shortest file name.
versionNoDefaults to the tag name without a leading "v".
nameNoRelease name. Defaults to the GitHub release name.
channelNorelease, beta or alpha. A GitHub prerelease becomes beta.
changelogNoMarkdown. Defaults to the GitHub release notes.
loadersNoComma-separated, for example "fabric,forge".
game-versionsNoComma-separated, for example "1.21.1,1.21.4".

Troubleshooting

When a publish is refused, the workflow step fails with a reason and a link to its entry here. Network and server errors are retried automatically.

  • token_missing

    The request had no GitHub Actions OIDC token.

    Fix: Use the allminecraft Action, and give the job the id-token: write permission. See Set it up above.

  • token_invalid

    The token could not be verified: it is expired, was issued for another audience, or is not from GitHub Actions.

    Fix: Run the Action again so it requests a fresh token. Do not reuse or cache tokens between runs.

  • no_publisher

    The post has no GitHub publisher set up on allminecraft.

    Fix: Open the post's editor, go to the Releases tab and choose Link GitHub. Under Choose your repository, enter the repository and workflow file and save, add the step to your workflow, then run the workflow again.

  • publisher_disabled

    The allminecraft team turned off publishing from GitHub for this post.

    Fix: The reason is shown under Link GitHub, on the post's Releases tab. Contact the allminecraft team to appeal.

  • repo_mismatch

    The run's repository is not the one set up for this post.

    Fix: Run the workflow from the configured repository, or change the repository under Link GitHub, on the Releases tab. The match is on the repository itself, not its name: renaming a repository is fine, but a fork, a repository transferred to another owner, or one deleted and created again counts as a different repository.

  • workflow_mismatch

    The run's workflow file is not the one set up for this post.

    Fix: Run the configured workflow file, or update the workflow file name under Link GitHub, on the Releases tab.

  • environment_mismatch

    The run's deployment environment is not the one set up for this post.

    Fix: Run the job in the configured environment, or update the environment under Link GitHub, on the Releases tab.

  • self_hosted_runner

    The job ran on a self-hosted runner. Whoever controls the machine controls the build, so the result cannot be trusted as coming from source.

    Fix: Change runs-on to a GitHub-hosted runner such as ubuntu-latest.

  • private_repo

    The repository is private. Publishing needs a public repository so that anyone can read the source.

    Fix: Make the repository public and run the workflow again. Private repositories are not supported yet.

  • pull_request_event

    The run was started by a pull request, which can come from a fork and is not allowed to publish.

    Fix: Trigger the workflow from a published GitHub release or a tag push instead.

  • attestation_invalid

    The build attestation for a file could not be checked.

    Fix: Attest the file with actions/attest-build-provenance (the allminecraft Action does this for you) before it is uploaded, with attestations: write granted.

  • attestation_mismatch

    The attestation does not match this run or this file, for example because the file changed after it was attested.

    Fix: Attest the exact file in the same workflow run that uploads it, and do not modify it afterwards.

  • post_not_publishable

    The post cannot take new releases right now, for example because its category has no releases or it was rejected, removed or deleted.

    Fix: Check the status of the post on allminecraft. The post must be in a release category and be a draft, waiting for review, or live.

  • author_not_allowed

    The post's author is not allowed to publish this way.

    Fix: Ask the allminecraft team about the author's account.

  • bad_request

    The request was malformed.

    Fix: Use the latest version of the Action (allminecraft/publish-action@v1). Calling the API directly is not supported.

  • too_many_files

    The release has more files than allowed.

    Fix: A release takes 1 to 3 files. Narrow the files glob so it matches at most 3.

  • file_too_large

    A file is over the size limit.

    Fix: Upload a smaller file, for example by removing unused assets from the build.

  • file_type

    A file has a type that is not accepted.

    Fix: Upload a mod, plugin, pack or world file in a supported format, such as .jar or .zip.

  • archive_rejected

    An archive could not be opened or has contents that are not supported.

    Fix: Rebuild the file, check that it opens locally, and publish again.

  • invalid_loaders

    One or more loaders in the loaders input are not recognised.

    Fix: Use comma-separated loader names that allminecraft lists, for example fabric,forge.

  • invalid_game_versions

    One or more Minecraft versions in the game-versions input are not recognised.

    Fix: Use comma-separated Minecraft versions that allminecraft lists, for example 1.21.1,1.21.4.

  • hash_mismatch

    An uploaded file does not match its declared SHA-256 hash.

    Fix: Run the workflow again. If it keeps happening, make sure nothing rewrites the file during the run.

  • upload_incomplete

    The release was finished before every declared file was uploaded.

    Fix: Run the workflow again. The Action uploads every file before it finishes.

  • session_not_found

    The publish session does not exist or has expired.

    Fix: Run the workflow again to start a new session.

  • version_exists

    A release with this version already exists on the post.

    Fix: Use a new version number: create a new tag, or set the version input. A version that exists cannot be overwritten.

  • session_closed

    The publish session is already finished.

    Fix: Run the workflow again to start a new session.

  • rate_limited

    Too many publish requests in a short time.

    Fix: Wait a few minutes, then run the workflow again.

  • unavailable

    Publishing from GitHub is not available on allminecraft right now.

    Fix: Try again later. The Action already retries server errors up to 3 times.

FAQ

Do I need an API key or a secret?
No. GitHub gives every workflow run a short-lived identity token, and that is all the Action uses. There is nothing to create, store or rotate.
Can I publish from a private repository?
Not yet. The repository must be public, so that anyone who sees the mark can read the code behind it.
Can I use GitLab, Jenkins or another CI?
Not yet. Publishing relies on GitHub Actions identity tokens.
Can I still upload by hand?
Yes, from the Releases tab of your post. Files uploaded by hand do not carry the Built from source mark.