Skip to content

Commit 0bf2764

Browse files
zefir-gitzefir-git
committed
update readme
1 parent c71d08e commit 0bf2764

File tree

1 file changed

+276
-71
lines changed

1 file changed

+276
-71
lines changed

‎README.md‎

Lines changed: 276 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,300 @@
11
# modrinth-publish
2-
A GitHub workflow for publishing plugin versions to Modrinth
32

4-
> [!NOTE]
5-
> This workflow only works for GitHub release events and only for plugins.
6-
7-
## Basic Usage
8-
Make sure that you run your GitHub action with:
3+
Publish a version on Modrinth. Works for all Modrinth project types.
4+
5+
## Usage
6+
97
```yaml
10-
on:
11-
release:
12-
types: [ published ]
8+
# …
9+
steps:
10+
- uses: cloudnode-pro/[email protected]
11+
with:
12+
token: ${{ secrets.MODRINTH_TOKEN }}
13+
# … configure the action using inputs here
1314
```
1415

15-
If the event is not `release`, this workflow will be skipped.
16+
## Inputs
17+
18+
### `api-domain`
19+
20+
Modrinth API domain. For testing purposes you can set this to `staging-api.modrinth.com`.
21+
See [Modrinth Staging Server](https://staging.modrinth.com).
22+
23+
<dl>
24+
<dt>Default</dt>
25+
<dd><code>api.modrinth.com</code></dd>
26+
</dl>
27+
28+
***
29+
30+
### `token` (required)
31+
32+
Modrinth API token. The token must have the ‘Create versions’ scope. This token is secret, and it’s recommended to set
33+
it inside
34+
a [GitHub Repository Secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
35+
36+
Personal access tokens (PATs) can be generated from [the user settings](https://modrinth.com/settings/pats).
37+
38+
***
39+
40+
### `project` (required)
41+
42+
The ID of the project this version is for.
43+
44+
You can obtain the ID by opening your project on Modrinth, then opening the <kbd>⋮</kbd> menu, and selecting <kbd>Copy
45+
ID</kbd>.
46+
47+
***
48+
49+
### `name`
50+
51+
The name of this version.
52+
53+
<dl>
54+
<dt>Default</dt>
55+
<dd>copied from <code>version</code></dd>
56+
</dl>
57+
58+
***
59+
60+
### `version` (required)
61+
62+
The version number. Ideally will follow [semantic versioning](https://semver.org/).
63+
64+
***
65+
66+
### `channel`
67+
68+
The release channel for this version.
69+
70+
<dl>
71+
<dt>Allowed values</dt>
72+
<dd><code>release</code>, <code>beta</code>, <code>alpha</code></dd>
73+
<dt>Default</dt>
74+
<dd>Inferred from the version.
75+
<ul>
76+
<li>If version includes <code>alpha</code>, will be set to <code>alpha</code>.</li>
77+
<li>If version includes <code>beta</code>, <code>rc</code>, or <code>pre</code>, will be set to <code>beta</code>.</li>
78+
<li>Otherwise, will be set to <code>release</code>.</li>
79+
</ul>
80+
</dd>
81+
</dl>
82+
83+
***
84+
85+
### `featured`
86+
87+
Whether the version is featured or not.
88+
89+
<dl>
90+
<dt>Allowed values</dt>
91+
<dd><code>true</code>, <code>false</code></dd>
92+
<dt>Default</dt>
93+
<dd><code>true</code> if the release channel is <code>release</code>, otherwise <code>false</code>.</dd>
94+
</dl>
95+
96+
***
97+
98+
### `changelog`
99+
100+
The changelog for this version.
101+
102+
***
103+
104+
### `loaders` (required)
105+
106+
The mod loaders that this version supports. In case of resource packs, use `minecraft`.
107+
108+
Format each loader on a new line, or use a JSON string array.
109+
110+
<dl>
111+
<dt>Example</dt>
112+
<dd>
16113

17-
Add the following step to your workflow:
18114
```yaml
19-
- name: Upload to Modrinth
20-
uses: cloudnode-pro/[email protected]
21-
with:
22-
token: ${{ secrets.MODRINTH_TOKEN }}
23-
project: AABBCCDD
24-
file: target/ProjectName-${{ github.event.release.tag_name }}.jar
25-
changelog: ${{ github.event.release.body }}
26-
loaders: paper, spigot
27-
api-domain: api.modrinth.com
115+
loaders: |-
116+
paper
117+
fabric
28118
```
29119
30-
Create a `MODRINTH_TOKEN` secret in your repository containing a Modrinth PAT (API token) with the "Create versions" permission. Replace the rest of the inputs with the desired values.
120+
```yaml
121+
loaders: '["paper", "fabric"]'
122+
```
123+
124+
</dd>
125+
</dl>
126+
127+
***
128+
129+
### `game-versions`
130+
131+
A list of versions of Minecraft that this version supports. You can use a pattern like `1.21.x` to include all patch
132+
versions (the last number in the version).
31133

32-
> [!NOTE]
33-
> This GitHub Action **will not** increment your project version or build/package your `.jar`. To do that, you will need to add additional steps to your workflow.
134+
Format each version on a new line, or use a JSON string array.
135+
136+
<dl>
137+
<dt>Example</dt>
138+
<dd>
139+
140+
```yaml
141+
game-versions: |-
142+
1.21.x
143+
1.20.x
144+
1.19.4
145+
```
34146

35-
### Example Maven Release Workflow
36147
```yaml
37-
name: Maven Release
38-
'on':
148+
game-versions: '["1.21.x", "1.20.x", "1.19.4"]'
149+
```
150+
151+
</dd>
152+
</dl>
153+
154+
***
155+
156+
### `files` (required)
157+
158+
A list of file paths to upload. There must be at least one file, unless the new version’s status is `draft`. The allowed
159+
file extensions are `.mrpack`, `.jar`, `.zip`, and `.litemod`.
160+
161+
Format each file on a new line, or use a JSON string array.
162+
163+
<dl>
164+
<dt>Example</dt>
165+
<dd>
166+
167+
```yaml
168+
files: |-
169+
target/YourProject-1.2.3.jar
170+
path/to/file.zip
171+
```
172+
173+
```yaml
174+
files: '["target/YourProject-1.2.3.jar", "path/to/file.zip"]'
175+
```
176+
177+
</dd>
178+
</dl>
179+
180+
***
181+
182+
### `primary-file`
183+
184+
The name (not path) from `files` to be set as the primary file.
185+
186+
<dl>
187+
<dt>Example</dt>
188+
<dd><code>YourProject-1.2.3.jar</code></dd>
189+
</dl>
190+
191+
***
192+
193+
### `dependencies`
194+
195+
A list of specific versions of projects that this version depends on.
196+
197+
Formatted as JSON array.
198+
See [Create Version - Modrinth API docs](https://docs.modrinth.com/api/operations/createversion/#request-body).
199+
200+
<dl>
201+
<dt>Example</dt>
202+
<dd>
203+
204+
```yaml
205+
dependencies: |-
206+
[{
207+
"project_id": "AABBCCDD",
208+
"dependency_type": "optional"
209+
}]
210+
```
211+
212+
</dd>
213+
</dl>
214+
215+
***
216+
217+
### `status`
218+
219+
<dl>
220+
<dt>Allowed values</dt>
221+
<dd><code>listed</code>, <code>archived</code>, <code>draft</code>, <code>unlisted</code>, <code>scheduled</code>, <code>unknown</code></dd>
222+
<dt>Default</dt>
223+
<dd><code>listed</code></dd>
224+
</dl>
225+
226+
***
227+
228+
### `requested-status`
229+
230+
<dl>
231+
<dt>Allowed values</dt>
232+
<dd><code>listed</code>, <code>archived</code>, <code>draft</code>, <code>unlisted</code></dd>
233+
</dl>
234+
235+
***
236+
237+
## Example Maven workflow
238+
239+
You can use the following example workflow to publish a version on Modrinth by creating a release on GitHub.
240+
241+
This example workflow will let you automatically build and upload a version on Modrinth whenever you publish a new
242+
release via GitHub. This enables you to choose the version tag and write release notes via the GitHub interface.
243+
244+
As the version will be taken from the release tag, in your `pom.xml` you can set a version like `0.0.0-SNAPSHOT` and it
245+
will always be replaced with the correct version for builds via the workflow. This means you won‘t need to update the
246+
version in multiple places.
247+
248+
<details name="example-workflow" open>
249+
<summary>Maven</summary>
250+
251+
```yaml
252+
name: Publish
253+
254+
on:
39255
release:
40-
types: [ published ]
256+
types: [published]
257+
41258
jobs:
42259
publish:
43-
name: Build and Upload JARs
260+
name: Publish
44261
runs-on: ubuntu-latest
45262
steps:
46-
- name: Checkout code
47-
uses: actions/checkout@v3
48-
- name: Set up Java
49-
uses: actions/setup-java@v3
263+
- name: Checkout repository
264+
uses: actions/checkout@v4
265+
266+
# !!! Make sure to select the correct Java version for your project !!!
267+
- name: Set up JDK 17
268+
uses: actions/setup-java@v4
50269
with:
51-
java-version: '17' # Make sure to set the correct Java version for your project
270+
java-version: 17
52271
distribution: temurin
53-
54-
# This step changes the version in your pom.xml to match the release tag
55-
# This change only happens in the workflow and is not committed to your repository.
56-
# You could set the version in your repository to something like `0.0.0-SNAPSHOT` and
57-
# it will always be overwritten to the correct version here when a release is created.
58-
- name: Set maven project ver
272+
cache: maven
273+
274+
# This step will take the version tag from the release and replace it in `pom.xml` before building.
275+
- name: Set version from release tag
59276
run: mvn -B versions:set -DnewVersion=${{ github.event.release.tag_name }} -DgenerateBackupPoms=false
60-
61-
# This step compiles your Maven project to a `.jar`
62-
- name: Build and package Maven project
63-
run: mvn clean package
64-
65-
# An optional step to also upload the `.jar` to the GitHub release assets
66-
- name: Upload to release
67-
uses: JasonEtco/upload-to-release@master
68-
with:
69-
# Make sure that this matches the file name of your .jar
70-
args: target/YourPlugin-${{ github.event.release.tag_name }}.jar application/java-archive
71-
env:
72-
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
73-
74-
# Upload the .jar to Modrinth
277+
278+
- name: Build and package with Maven
279+
run: mvn -B clean package --file pom.xml
280+
75281
- name: Upload to Modrinth
76-
uses: cloudnode-pro/modrinth-publish@1.0.0
282+
uses: cloudnode-pro/modrinth-publish@2.0.0
77283
with:
78-
token: '${{ secrets.MODRINTH_TOKEN }}' # You need to create this secret in your repository settings
79-
project: AABBCCDD # Replace with your project id/slug
80-
file: 'target/YourPlugin-${{ github.event.release.tag_name }}.jar' # Make sure that this matches the file name of your .jar
81-
changelog: '${{ github.event.release.body }}' # Copies the version changelog from the GitHub release notes
82-
loaders: 'paper, spigot' # A list of your supported loaders
83-
284+
# Configure the action as needed. The following is an example.
285+
token: ${{ secrets.MODRINTH_TOKEN }}
286+
project: AABBCCDD
287+
name: ${{ github.event.release.name }}
288+
version: ${{ github.event.release.tag_name }}
289+
changelog: ${{ github.event.release.body }}
290+
loaders: |-
291+
paper
292+
spigot
293+
bukkit
294+
game-versions: |-
295+
1.20.x
296+
1.21.x
297+
files: target/YourProject-${{ github.event.release.tag_name }}.jar
84298
```
85299
86-
## Input Options
87-
| Parameter | Required | Description |
88-
|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
89-
| `token` | yes | Modrinth API token |
90-
| `project` | yes | Modrinth project ID |
91-
| `file` | yes | Path to file to upload |
92-
| `changelog` | no | The changelog for this version (markdown). Defaults to GitHub release notes. |
93-
| `loaders` | yes | The mod loaders that this version supports (separated by commas or as JSON string array). See [createVersion](https://docs.modrinth.com/api-spec#tag/versions/operation/createVersion) |
94-
| `dependencies` | no | A list of specific versions of projects that this version depends on (as JSON array). See [createVersion](https://docs.modrinth.com/api-spec#tag/versions/operation/createVersion) |
95-
| `api-domain` | no | Modrinth API domain. For testing purposes you can set this to `staging-api.modrinth.com`. See [Modrinth Staging Server](https://staging.modrinth.com) | |
300+
</details>

0 commit comments

Comments
 (0)