✦ YMIR MODS

For mod creators

Your GitHub release.
Your next YMIR update.

Publish a release on GitHub and let GitHub Actions upload it to your existing YMIR Mods listing. GitHub sign-in identifies your account; the workflow below handles publishing.

1. Set up your mod once

  1. Sign in to YMIR Mods and upload your mod once. You must own the listing you update.
  2. Copy its slug from the address. For https://ymirmods.com/mod/my-mod, the slug is my-mod.
  3. Open Dashboard → Creator API Keys, name a key for this repository, and generate it. The full key appears only once.
  4. In your GitHub mod repository, open Settings → Secrets and variables → Actions. Under Secrets, add YMIR_API_KEY with that key.
  5. Under Variables, add YMIR_MOD_SLUG with the slug. If your release contains multiple ZIPs, also set YMIR_ASSET_PATTERN, for example MyMod-*.zip. Exactly one uploaded asset must match.
  6. Download or copy the workflow below. Add it to your repository as .github/workflows/ymir-release.yml and commit it to the default branch before making your next release.

Repeat for each mod repository. A repository with several different mods needs a separate configured job for each listing; this template publishes one mod per repository. API keys can update mods owned by their creator: keep them in GitHub secrets and revoke them from your dashboard when no longer needed.

2. Publish your next release

  1. Build your installable mod ZIP. Include manifest.json at the ZIP root with a version_number such as 1.2.3. Root-level README.md and icon.png are optional and update the listing when present.
  2. Create a draft GitHub release, attach the ZIP, and write your release notes. GitHub's automatically generated source-code archives are not installable release assets and are not selected.
  3. Use a matching tag, such as v1.2.3 or 1.2.3, then publish the stable release. Drafts and prereleases are excluded by this template.
  4. Open the repository's Actions tab and select Publish release to YMIR Mods to check the result.

The ZIP becomes the new download. Release notes become the changelog. An omitted README or icon preserves the current description or icon. YMIR retains the latest release plus two older versions.

Existing release? Choose Actions → Publish release to YMIR Mods → Run workflow and enter its exact tag. Repeating an already published version returns a conflict instead of replacing it. Upload your first manual version, then use a newer version for the first automatic update.

If another workflow creates your GitHub release using its built-in GITHUB_TOKEN, that release may not trigger a second workflow. Add the publish step after the asset-upload step in your existing release workflow, or run this workflow manually. Attaching assets after publication also needs a manual run.

3. Add the workflow

Download workflow

Save as .github/workflows/ymir-release.yml. No extra action or repository checkout is required. This template limits ZIPs to 95 MiB to leave room below the hosting request-size limit; the API's own package validation limit is 500 MiB, but it cannot bypass hosting limits.

name: Publish release to YMIR Mods
on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      tag:
        description: Existing stable release tag (e.g. v1.2.3)
        required: true
        type: string
permissions:
  contents: read
concurrency:
  group: ymir-publish-${{ github.repository }}
  cancel-in-progress: false
jobs:
  publish:
    if: github.event_name == 'workflow_dispatch' || github.event.release.prerelease == false
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Download package and publish
        env:
          GH_TOKEN: ${{ github.token }}
          YMIR_API_KEY: ${{ secrets.YMIR_API_KEY }}
          YMIR_MOD_SLUG: ${{ vars.YMIR_MOD_SLUG }}
          YMIR_ASSET_PATTERN: ${{ vars.YMIR_ASSET_PATTERN }}
          RELEASE_TAG: ${{ inputs.tag }}
        shell: bash
        run: |
          python3 - <<'PY'
          import fnmatch, json, os, pathlib, re, subprocess, sys, zipfile
          def fail(message):
              raise SystemExit(message)
          slug = os.environ.get("YMIR_MOD_SLUG", "").strip()
          key = os.environ.get("YMIR_API_KEY", "").strip()
          if not re.fullmatch(r"[a-z0-9-]+", slug):
              fail("Set repository variable YMIR_MOD_SLUG to the slug from your YMIR mod URL.")
          if not key:
              fail("Add repository secret YMIR_API_KEY.")
          event = json.loads(pathlib.Path(os.environ["GITHUB_EVENT_PATH"]).read_text())
          tag = event.get("release", {}).get("tag_name") or os.environ.get("RELEASE_TAG", "")
          if not tag or tag.startswith("-"):
              fail("A published release tag is required.")
          release = json.loads(subprocess.check_output(
              ["gh", "release", "view", tag, "--repo", os.environ["GITHUB_REPOSITORY"],
               "--json", "tagName,body,assets,isDraft,isPrerelease"], text=True))
          if release["isDraft"] or release["isPrerelease"]:
              fail("Only published stable releases are supported by this workflow.")
          pattern = os.environ.get("YMIR_ASSET_PATTERN", "").strip() or "*.zip"
          assets = [a for a in release["assets"] if fnmatch.fnmatchcase(a["name"], pattern)]
          if len(assets) != 1:
              fail("Expected exactly one matching release asset. Set YMIR_ASSET_PATTERN, e.g. MyMod-*.zip.")
          asset = assets[0]
          if not asset["name"].lower().endswith(".zip") or "/" in asset["name"] or "\\" in asset["name"]:
              fail("Select a ZIP release asset with a plain filename.")
          if asset["size"] <= 0 or asset["size"] > 95 * 1024 * 1024:
              fail("This workflow supports packages up to 95 MiB; larger uploads may exceed the website request limit.")
          folder = pathlib.Path("ymir-package")
          folder.mkdir()
          subprocess.run(["gh", "release", "download", tag, "--repo", os.environ["GITHUB_REPOSITORY"],
                          "--pattern", asset["name"], "--dir", str(folder)], check=True)
          package = folder / asset["name"]
          with zipfile.ZipFile(package) as archive:
              def member(name, limit, required=False):
                  matches = [i for i in archive.infolist() if i.filename.lower() == name.lower()]
                  if len(matches) > 1:
                      fail("Duplicate ZIP member: " + name)
                  if not matches:
                      if required:
                          fail("ZIP must contain " + name + " at its root.")
                      return None
                  if matches[0].file_size > limit:
                      fail("ZIP member too large: " + name)
                  return archive.read(matches[0])
              manifest = json.loads(member("manifest.json", 65536, True).decode("utf-8-sig"))
              version = str(manifest.get("version_number", "")).strip()
              if not version or len(version) > 32:
                  fail("manifest.json needs a valid version_number (maximum 32 characters).")
              expected = tag[1:] if tag.startswith("v") else tag
              if expected != version:
                  fail("Release tag must match manifest version_number, optionally prefixed with v.")
              readme = member("README.md", 400000)
              icon = member("icon.png", 5 * 1024 * 1024)
              fields = {"version": version, "changelog": release.get("body") or ""}
              if len(fields["changelog"]) > 50000:
                  fail("Release notes exceed the 50,000-character API limit.")
              if readme is not None:
                  description = readme.decode("utf-8-sig")
                  if len(description) > 100000:
                      fail("README exceeds the 100,000-character API limit.")
                  fields["full_description"] = description
          # Build multipart without interpolating release text into shell commands.
          import uuid
          boundary = "ymir-" + uuid.uuid4().hex
          parts = []
          for name, value in fields.items():
              parts.append(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"" +
                            name + "\"\r\n\r\n" + value + "\r\n").encode())
          def file_part(name, filename, mime, data):
              return (("--" + boundary + "\r\nContent-Disposition: form-data; name=\"" + name +
                       "\"; filename=\"" + filename + "\"\r\nContent-Type: " + mime +
                       "\r\n\r\n").encode() + data + b"\r\n")
          parts.append(file_part("mod_file", "package.zip", "application/zip", package.read_bytes()))
          if icon is not None:
              parts.append(file_part("icon_file", "icon.png", "image/png", icon))
          parts.append(("--" + boundary + "--\r\n").encode())
          import urllib.request, urllib.error
          class NoRedirect(urllib.request.HTTPRedirectHandler):
              def redirect_request(self, *args, **kwargs):
                  return None
          request = urllib.request.Request(
              "https://ymirmods.com/api/v1/mods/" + slug + "/releases",
              data=b"".join(parts),
              headers={"Authorization": "Bearer " + key,
                       "Content-Type": "multipart/form-data; boundary=" + boundary}, method="POST")
          try:
              with urllib.request.build_opener(NoRedirect).open(request, timeout=180) as response:
                  result = json.load(response)
              if not result.get("success"):
                  fail("YMIR did not report a successful publish.")
          except urllib.error.HTTPError as error:
              hints = {401: "Invalid/revoked API key.", 403: "The API key must belong to the mod owner and allow updates.",
                       404: "Create the mod on YMIR first and check YMIR_MOD_SLUG.",
                       409: "This version already exists. Nothing was overwritten; publish a new version.",
                       413: "Package exceeds the server upload limit."}
              fail("YMIR HTTP " + str(error.code) + ": " + hints.get(error.code, "Check package fields and website availability."))
          print("Published " + version + " to https://ymirmods.com/mod/" + slug)
          
          PY

Creator API reference

Base URL: https://ymirmods.com. Authenticate with Authorization: Bearer YOUR_API_KEY. Use multipart form data for uploads. All requests use HTTPS.

Method & pathPurpose
GET /api/v1/meCheck key identity, scopes, and upload permission. Requires mods:read.
POST /api/v1/modsCreate a listing without the manual form. Requires mods:upload. Slug is generated from the mod name; read it from the response.
POST /api/v1/mods/{slug}/releasesPublish a new version of an owned listing. Requires mods:update.

Publish-release fields

version (required, up to 32 characters), mod_file (required nonempty ZIP), changelog (up to 50,000 characters), full_description (optional, up to 100,000 characters), icon_file (optional PNG, JPEG, or WebP up to 5 MiB).

Create-mod fields

Use the release fields plus name (2–80 characters), category (2–60 characters), and short_description (10–250 characters). There is no automatic import of all GitHub repositories.

curl --fail-with-body --request POST \
  --header "Authorization: Bearer $YMIR_API_KEY" \
  --form-string "version=1.2.3" \
  --form "mod_file=@MyMod.zip;type=application/zip" \
  --form "changelog=<CHANGELOG.md" \
  --form "full_description=<README.md" \
  https://ymirmods.com/api/v1/mods/my-mod/releases

Set YMIR_API_KEY through your secret manager or workflow environment. Do not paste a real key into committed scripts. Do not automatically retry an upload after an ambiguous timeout: check whether the version exists first.

If a release does not publish

ResultWhat to check
No workflow runCommit the YAML before creating the release. Publish a stable release with the ZIP already attached. See the note about releases created by another workflow above.
Asset selection errorAttach an installable ZIP. Set YMIR_ASSET_PATTERN to match exactly one ZIP.
Version mismatchMatch the release tag to the ZIP manifest's version_number.
401Set the repository secret correctly; generate a new key if revoked.
403The API key's account must own the listing and have upload permission and the required scope.
404Create the mod first and check the exact slug.
409That version already exists. Use a new version for an update.
413The upload exceeds a server or hosting size limit.

The workflow is a publishing template, not a compiler: it does not build DLLs, generate the ZIP, or delete YMIR releases when a GitHub release is deleted.