Publish your mod with lip
At the end of this tutorial your mod has its first release on GitHub, and anyone can install it on their server with one command, lip install github.com/<you>/my-mod. You describe the mod in lip.toml, let GitHub Actions build the release, check that lip sees it, install it on your own server, and get it listed on LeviMC Mods.
It takes about half an hour, most of it waiting for the release build.
What you need
- A mod in a public GitHub repository created from the mod template, which builds: Your first LeviLamina mod. This tutorial calls the repository
github.com/<you>/my-mod. lipand a server to test on: Your first server. This tutorial usesD:\servers\survival.- Git, signed in to GitHub so that you can push.
lip 0.41 needed
The lip pkg … commands of this tutorial come with lip 0.41, a pre-release until its final version is out (lip 0.40 does not have them). Check with lip -v, and install the newest 0.41 from the releases of lip if needed.
A package is anything lip can install. Its package id is the address of its repository without https://: github.com/<you>/my-mod. A version is a Git tag v + the version, such as v0.1.0, at which lip.toml says the same version. There is no upload step: publishing is pushing that tag.
1. Fill in lip.toml
The template comes with a lip.toml, the file that tells lip what to install. Open it and change these fields. Leave the rest as it is.
format = 4
id = "github.com/<you>/my-mod" # the package id: your repository
version = "0.1.0" # the version you are about to release, without "v"
[info] # shown on LeviMC Mods and in LeviLauncher; lip ignores it
name = "My Mod"
description = "Says hello."
tags = ["utility"]
logo = "https://avatars.githubusercontent.com/u/<your user id>"Then, in both [[variants.""]] entries (one with side = "server", one with side = "client"):
- In
deps, set the range of LeviLamina versions the mod works with. The server entry takes a range such as"26.60.*", matching the version you pinned inxmake.lua. Keep the comment and the form of the client range. - In
urls, replacelevilamina-mod-templatewith the name of your repository: the release workflow uploads<repository>-server-windows-x64.zipand<repository>-client-windows-x64.zip. - In
place, replacemy-modwith the target name ofxmake.lua, insrcand indest: each ZIP file holds the folder<target>/, which goes tomods/<target>/.
If your mod is for the server only, delete the whole client entry: the [[variants.""]] with side = "client" and the deps and assets below it.
{{id}} and {{version}}
Every string in lip.toml is a template. {{version}} becomes the version above, so a new release only needs a new version. {{id}} becomes the package id.
A repository without lip.toml, or with tooth.json
For a repository that is not from the template, run lip pkg init in its root: it asks for the package id and writes a minimal lip.toml to fill in as above. A tooth.json from lip v0.x is converted with lip pkg migrate; see Migrating packages.
2. Check that lip reads it
In the repository folder, run:
lip pkg view .You should see JSON: under manifest, your id and version, and the urls with the templates filled in, such as https://github.com/<you>/my-mod/releases/download/v0.1.0/my-mod-server-windows-x64.zip. Check that these names match your repository. If something is wrong in the file, lip says what instead.
3. Write the changelog
The release workflow copies the newest section of CHANGELOG.md into the release notes. Add a section for the version, in the Keep a Changelog format:
## [0.1.0] - 2026-11-16
### Added
- The `/hello` command.Commit and push everything:
git add -A
git commit -m "Release 0.1.0"
git push4. Create the release
- On the page of your repository on GitHub, open Releases → Draft a new release.
- Under Choose a tag, type
v0.1.0and choose Create new tag: v0.1.0 on publish. The target is your default branch, with the commit you just pushed. - Give the release a title, such as
0.1.0, and press Publish release. - Open the Actions tab. A workflow run has started for the release: it builds the server and the client mod, then uploads them. Wait until it has a green tick (a few minutes).
- Open the release again. You should see two files under Assets:
my-mod-server-windows-x64.zipandmy-mod-client-windows-x64.zip, and your changelog as the notes.
The tag must match version
The tag is v followed by a full semantic version: v0.1.0, not 0.1.0 or v0.1. At the tag v0.1.0, lip.toml must say version = "0.1.0", or lip, LeviMC Mods and LeviLauncher skip the tag.
5. Check that lip sees the version
From any folder, run:
lip pkg view github.com/<you>/my-modYou should see "versions": ["0.1.0"] at the end, and under manifest the lip.toml you tagged.
6. Install it like your users will
-
Stop your server. If the mod is still in
mods\my-modfrom the previous tutorial, delete that folder, so that what you test is only whatlipinstalls. -
In the server folder, install your package:
shellcd D:\servers\survival lip install github.com/<you>/my-mod lip listlip listshould showgithub.com/<you>/my-mod@0.1.0. -
Start the server. You should see
Hello from my first mod!again, now from the fileslipdownloaded.
Players install the client build of the same package with LeviLauncher, once the mod is listed (step 7): see Play with mods on Windows.
7. Get listed on LeviMC Mods
LeviMC Mods is the catalog that lip's Get mods page and LeviLauncher show. It is built from a list of repositories, mods/repos.txt in the levimc.org repository.
You usually do not need to do anything: every two hours a bot searches GitHub for repositories with a lip.toml and a version tag that lip can read, and opens a pull request that adds them to the list. Once a maintainer merges it, the mod appears at the next hourly build.
To be listed sooner, open that pull request yourself: edit mods/repos.txt on GitHub and add a line <you>/my-mod.
The catalog lists a package when:
- its latest version depends on LeviLamina, directly or through other packages;
- it places files in
mods/(orplugins/, or where the game loads add-ons from); - the repository is not a GitHub template and its name does not end in
-template,-example,-demo,-sampleor-test.
You should then find your mod at https://levimc.org/mods/github.com/<you>/my-mod/, with its name, description, logo, tags and the command to install it.
Releasing the next version
- Raise
versioninlip.toml, such as0.2.0, and add its section toCHANGELOG.md. Commit and push. - Create the release
v0.2.0as in step 4. - On a server,
lip update github.com/<you>/my-modinstalls it.
What you have now
- A release of your mod on GitHub, built by GitHub Actions.
- A package that installs with
lip install github.com/<you>/my-mod, with its dependency on LeviLamina. - Your mod on LeviMC Mods, once the list includes it.
Next steps
- Every field of
lip.toml: dependencies, variants, files to keep or delete, hooks: lip.toml. - The commands for package authors:
lip pkg init,lip pkg pack,lip pkg view,lip pkg migrate. - Install a branch or a commit before you release it: Managing packages.
- The same tools in the interface of
lip: Tools. - How servers install your package: Install mods on your server.