How to Publish Your First Mod on OpenMods

If you're a modder and your work already lives on GitHub, publishing on OpenMods is mostly about pointing at a repo and letting the platform handle the rest. This guide walks through the full flow end-to-end, with screenshots of what to expect at each step.

What OpenMods does (in one paragraph)

OpenMods is a discovery and distribution layer for game mods. You publish your mod once, to GitHub, with proper releases. OpenMods then handles the catalog page, search, version tracking, download counts, comments, and end-user installation through OpenModsManager. You keep your source on GitHub, your releases on GitHub, your CI on GitHub. We just give the mod a public face.

Go to openmods.net, click Sign in, and authorise the OpenMods OAuth app. This uses GitHub OAuth (PKCE flow), not a password — you'll never type a password into OpenMods.

After the redirect, you'll land on the dashboard at /dashboard. Your developer profile (display name, avatar, bio) is auto-populated from your public GitHub profile. You can edit any of it later from the profile settings.

Step 2 — Install the OpenMods GitHub App

On your first visit to the dashboard, you'll see a banner inviting you to Install GitHub App. Click it and you'll be sent to GitHub's app-install flow. You can install the OpenMods App on:

Your personal account — gives OpenMods access to your own repos
An organisation you administer — gives access to that org's repos

GitHub will let you pick exactly which repositories the App can read. Pick the ones containing mods you want to publish. You can always add or remove repos later from your GitHub settings.

Why a GitHub App and not just OAuth? Two reasons. First, it lets OpenMods read your repos with the App's identity rather than yours, so a token revocation later doesn't break sync. Second, it lets us subscribe to webhooks — when you publish a new release, OpenMods sees it within seconds and updates the mod page automatically.

Step 3 — Connect your first repository

Once the App is installed, the dashboard shows a Connect repository button. Clicking it opens a modal listing every repo the App has access to. Pick one, then:

Choose the game — search the supported-games list. If your game isn't listed, click "Request a game" — we'll add it.
Configure metadata — title (defaults to the repo name), short description (defaults to the GitHub repo description), a hero image URL, and tags. These can all be edited later.
Confirm — the platform pulls the README, the latest few releases (with their assets), star count, and last-updated timestamp.

That's it for setup. Your mod page is live the moment you save.

Step 4 — Cut a release on GitHub

Releases are how OpenMods knows what to serve when a user clicks Download. The platform reads from your repository's GitHub Releases — not from the default branch.

A minimal release looks like:

Create a Git tag (semantic versioning: v1.0.0, v1.1.0, v1.1.1).
Go to the repo's Releases tab → Draft a new release.
Pick the tag, add release notes (these become the mod's changelog on OpenMods), and attach the build artifact — usually a .zip containing the compiled .dll or the mod folder.
Publish the release.

OpenMods receives the webhook within seconds and the new release appears on your mod page. Pre-releases on GitHub are also shown, but flagged as such — users have to opt in to download them.

Step 5 — What goes on the public page

Your published mod has a page at /mods/{game}/{mod-slug} showing:

The README, rendered with the same Markdig pipeline as everywhere else on the site
A version dropdown with download buttons for each release's assets
View and download counters (anonymised per-day per-visitor to avoid bot inflation)
Stars synced from GitHub
A comments section (you can disable it from the mod's settings if you'd rather not moderate)
An author footer card linking back to your developer profile

The mod page is server-rendered, has its own canonical URL, sitemap entry, and OpenGraph metadata. It's indexable from day one.

Step 6 — Subsequent updates

You don't need to come back to the OpenMods dashboard for routine updates. Cut a new GitHub release, the page updates itself. The dashboard is where you go to:

Edit metadata (title, description, hero image, tags)
Archive a mod (hides it from search without deleting it)
Set a parent mod (for dependencies / forks)
Manage API keys if you want programmatic access to your own mod's stats

What if I don't use GitHub?

You'll need GitHub to publish on OpenMods today. There's no manual upload path — the design assumes your source and releases live there. If your mod's primary home is GitLab or Codeberg, the path of least resistance is to mirror the repo to GitHub. We may add other forges in the future, but it's not on the near-term roadmap.

Common gotchas

No releases yet? The mod page will load, but the download button will be greyed out. Publish at least one GitHub release before announcing the page.
README too long? Markdig handles ~200 KB cleanly. If your README is genuinely longer than that, split it into a wiki and link out from the README.
Game not on the list? Click "Request a game" from the repo-connection modal. We add games on request — typically within a day.
Mod stuck on "Syncing"? The first sync takes 30–60 seconds while we pull releases and the README. If it's been more than five minutes, open a support ticket and we'll look.

That's the full flow. The whole setup, from sign-in to a public mod page with a live download button, is usually under ten minutes.