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
- Sign in to YMIR Mods and upload your mod once. You must own the listing you update.
- Copy its slug from the address. For
https://ymirmods.com/mod/my-mod, the slug ismy-mod. - Open Dashboard → Creator API Keys, name a key for this repository, and generate it. The full key appears only once.
- In your GitHub mod repository, open Settings → Secrets and variables → Actions. Under Secrets, add
YMIR_API_KEYwith that key. - Under Variables, add
YMIR_MOD_SLUGwith the slug. If your release contains multiple ZIPs, also setYMIR_ASSET_PATTERN, for exampleMyMod-*.zip. Exactly one uploaded asset must match. - Download or copy the workflow below. Add it to your repository as
.github/workflows/ymir-release.ymland 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
- Build your installable mod ZIP. Include
manifest.jsonat the ZIP root with aversion_numbersuch as1.2.3. Root-levelREADME.mdandicon.pngare optional and update the listing when present. - 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.
- Use a matching tag, such as
v1.2.3or1.2.3, then publish the stable release. Drafts and prereleases are excluded by this template. - 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 workflowSave 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 & path | Purpose |
|---|---|
GET /api/v1/me | Check key identity, scopes, and upload permission. Requires mods:read. |
POST /api/v1/mods | Create 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}/releases | Publish 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
| Result | What to check |
|---|---|
| No workflow run | Commit 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 error | Attach an installable ZIP. Set YMIR_ASSET_PATTERN to match exactly one ZIP. |
| Version mismatch | Match the release tag to the ZIP manifest's version_number. |
| 401 | Set the repository secret correctly; generate a new key if revoked. |
| 403 | The API key's account must own the listing and have upload permission and the required scope. |
| 404 | Create the mod first and check the exact slug. |
| 409 | That version already exists. Use a new version for an update. |
| 413 | The 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.