User Tools

Site Tools


tutorial:publishing_mods_using_github_actions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
tutorial:publishing_mods_using_github_actions [2022/11/19 18:09] – Adjust title to be closer to similar tutorials xipittutorial:publishing_mods_using_github_actions [2023/04/10 09:04] (current) – Fix typos and capitalisation poopooracoocoo
Line 1: Line 1:
-====== Publishing mods on Curseforge, Modrinth & Github with MC-Publish ======+====== Publishing mods on CurseForge, Modrinth & GitHub with MC-Publish ======
  
-MC-Publish is a Github Action by Kir-Antipov that communicates with GithubCurseforge and Mordrinth APIs to upload your mod files. This page only goes through the basics of the set-up and you should [[https://github.com/Kir-Antipov/mc-publish#publish-minecraft-mods---github-action|check out its Github documentation for further information]].+MC-Publish is a GitHub Action by Kir-Antipov that communicates with GitHubCurseForge and Modrinth APIs to upload your mod files. This page only goes through the basics of the set-up and you should [[https://github.com/Kir-Antipov/mc-publish#publish-minecraft-mods---github-action|check out its Github documentation for further information]].
  
-===== What are Github Actions? =====+===== What are GitHub Actions? =====
  
-[[https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions|Github Actions]] are essentially commands that get executed on Github servers. They are free to use as long as your Github repository is public and come with a limit, that should not hinder you, if it isn't. +[[https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions|Github Actions]] are essentially commands that get executed on GitHub servers. They are free to use as long as your GitHub repository is public and come with a limit, that should not hinder you, if it isn't. 
-In Software Development Github Actions and similar workflow automation systems are standard place and help tremendously with making deployments (such as releasing a new version of your mod) as seemless as possible.      +In Software Development Github Actions and similar workflow automation systems are standard place and help tremendously with making deployments (such as releasing a new version of your mod) as seamless as possible.      
  
-If you dread the manual process of uploading your mod to multiple platforms this is the solution.+If you dread the manual process of uploading your mod to multiple platformsthis is the solution.
  
  
Line 14: Line 14:
  
 You should have already done the following: You should have already done the following:
-  - create a repository of your mod on Github +  - create a repository of your mod on GitHub 
-  - upload a version of your mod to Curseforge and Modrinth and have it approved+  - upload a version of your mod to CurseForge and Modrinth and have it approved
  
  
 ===== Setup ===== ===== Setup =====
  
-If we want Github to do something for us, we need to tell their servers what exactly we want. To do that we need to add a ''.yml'' file in ''/.github/workflows''. You can think of this ''.yml'' file as the config file of your Github Action. It does not matter how it is named, you should however pick a relevant name. [[https://de.wikipedia.org/wiki/YAML|YAML]] is generally similar to JSON in concept, but has a very different syntax. Just like Python you dont use curly braces ''{}'' and instead only use indention to declare your structure.+If we want Github to do something for us, we need to tell their servers what exactly we want. To do that we need to add a ''.yml'' file in ''/.github/workflows''. You can think of this ''.yml'' file as the config file of your Github Action. It does not matter how it is named, you should however pick a relevant name. [[https://de.wikipedia.org/wiki/YAML|YAML]] is generally similar to JSON in concept, but has a very different syntax. Just like Python you don'use curly braces ''{}'' and instead only use indention to declare your structure.
  
 The general structure of your ''.yml'' file should look like this: The general structure of your ''.yml'' file should look like this:
  
 <code yaml> <code yaml>
-name: Publish on GithubCurseforge & Modrinth    #The name of your Github Action on Github.com+name: Publish on GitHubCurseForge & Modrinth    #The name of your GitHub Action on github.com
    
-on: [ pull_request, workflow_dispatch ]           #When your Github Action will be executed ('pull_request' -> on every Merge(/Pull) Request; 'workflow_dispatch' -> allows manual execution through Github.com+on: [ pull_request, workflow_dispatch ]           #When your GitHub Action will be executed ('pull_request' -> on every Merge(/Pull) Request; 'workflow_dispatch' -> allows manual execution through github.com
  
 env:                                              #Environment variables that can later be referenced using ${{ env.MINECRAFT_VERSION }}. These are useful for repeating information and allow for quick changes for new mod updates env:                                              #Environment variables that can later be referenced using ${{ env.MINECRAFT_VERSION }}. These are useful for repeating information and allow for quick changes for new mod updates
Line 36: Line 36:
   contents: write   contents: write
  
-jobs:                                             #The place where you actually tell the Github server what to do. +jobs:                                             #The place where you actually tell the GitHub server what to do. 
   build:                                          #To publish your mod you only need one 'job', here it is called 'build'.   build:                                          #To publish your mod you only need one 'job', here it is called 'build'.
     runs-on: ubuntu-latest                        #'runs-on' specifies the operation system (linux).     runs-on: ubuntu-latest                        #'runs-on' specifies the operation system (linux).
Line 43: Line 43:
 </code> </code>
  
-I recommend to keep ''on: [ pull_request, workflow_dispatch ]'' and adapt your usage of git branches accordingly. This means developing every update on its own branch and only merging into main when its ready to be released. If this absolutely does not fit your needs you can [[https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows|check for different triggers]] or just use ''workflow_dispatch''. Remember that you dont want to accidently start your Github Action while setting up.+I recommend to keep ''on: [ pull_request, workflow_dispatch ]'' and adapt your usage of git branches accordingly. This means developing every update on its own branch and only merging into main when its ready to be released. If this absolutely does not fit your needs you can [[https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows|check for different triggers]] or just use ''workflow_dispatch''. Remember that you dont want to accidently start your GitHub Action while setting up.
  
 Basic environments variables should include: Basic environments variables should include:
Line 80: Line 80:
    * ''name'' The name of the step, should accurrately describe the step.    * ''name'' The name of the step, should accurrately describe the step.
    * ''if'' A condition that needs to return true in order for the step to execute.    * ''if'' A condition that needs to return true in order for the step to execute.
-   * ''uses'' Here you can specify additional Github Actions. You could program everything yourself, but where is the point in that if someone already did that for you? MC-Publish by Kir-Antipov is an example of that. +   * ''uses'' Here you can specify additional GitHub Actions. You could program everything yourself, but where is the point in that if someone already did that for you? MC-Publish by Kir-Antipov is an example of that. 
-   * ''with'' If you specified a Github Action with ''uses'' you can input predefined variables with your own values.+   * ''with'' If you specified a GitHub Action with ''uses'' you can input predefined variables with your own values.
    * ''run'' Execute a command on the command line.    * ''run'' Execute a command on the command line.
  
Line 123: Line 123:
 === MC-Publish === === MC-Publish ===
  
-This section will by its nature not be complete, to get a full overview you can [[https://github.com/Kir-Antipov/mc-publish#publish-minecraft-mods---github-action|check the official Github Documentation of MC-Publish]]. +This section will by its nature not be complete, to get a full overview you can [[https://github.com/Kir-Antipov/mc-publish#publish-minecraft-mods---github-action|check the official GitHub Documentation of MC-Publish]]. 
  
 <code yaml> <code yaml>
Line 132: Line 132:
       ...       ...
              
-      - name: Publish (CurseForge/Modrinth/Github+      - name: Publish (CurseForge/Modrinth/GitHub
-        uses: Kir-Antipov/mc-publish@v3.2                                   #The specified MC-Publish Github Action in the version 3.2+        uses: Kir-Antipov/mc-publish@v3.2                                   #The specified MC-Publish GitHub Action in the version 3.2
         with:         with:
-          curseforge-id: 123456                                             #The id of your curseforge project+          curseforge-id: 123456                                             #The id of your CurseForge project
           curseforge-token: "${{env.CURSEFORGE_TOKEN}}"           curseforge-token: "${{env.CURSEFORGE_TOKEN}}"
                      
Line 156: Line 156:
 ''CURSEFORGE_TOKEN'', ''MODRINTH_TOKEN'' or ''GITHUB_TOKEN'' are essentially passwords that are used to authenticate you as a person, that means these are specific to your account and **not** to your mod. This makes sure that only you can push updates through the API. When uploading normally you authenticate yourself when you log in. Where do you find these authentication tokens? It's different for every platform: ''CURSEFORGE_TOKEN'', ''MODRINTH_TOKEN'' or ''GITHUB_TOKEN'' are essentially passwords that are used to authenticate you as a person, that means these are specific to your account and **not** to your mod. This makes sure that only you can push updates through the API. When uploading normally you authenticate yourself when you log in. Where do you find these authentication tokens? It's different for every platform:
  
-**//Github//** Settings > Developer Settings > Personal access tokens > Tokens (classic) => press "Generate new token" and choose classic => select the 'repo' scope (write a descriptive note, 90 days expiration is recommended, you will need to generate a new token afterwards) => press "Generate token"+**//GitHub//** Settings > Developer Settings > Personal access tokens > Tokens (classic) => press "Generate new token" and choose classic => select the 'repo' scope (write a descriptive note, 90 days expiration is recommended, you will need to generate a new token afterwards) => press "Generate token"
  
 **//Modrinth//** Settings => Authorization token  **//Modrinth//** Settings => Authorization token 
  
-**//Curseforge//** Settings > My API Tokens => choose a descriptive name and press "Generate Token"   +**//CurseForge//** Settings > My API Tokens => choose a descriptive name and press "Generate Token"   
  
-It is **strongly recommended** that you save the authentication tokens somewhere safe, e.g. a password manager. **Github //won't// let you access your token after you have generated it!**+It is **strongly recommended** that you save the authentication tokens somewhere safe, e.g. a password manager. **GitHub //won't// let you access your token after you have generated it!**
  
  
-Now that you have all the tokens you need, you have to make them accessible to your Github Action. Go to the settings page of your mod repository on Github.com and navigate to Secrets > Actions. Add all your authentication tokens as secrets. You will need to reference the name you give them here in your ''.yml'' file. A secret named ''PUBLISH_CURSEFORGE_TOKEN'' can be referenced using +Now that you have all the tokens you need, you have to make them accessible to your GitHub Action. Go to the settings page of your mod repository on github.com and navigate to Secrets > Actions. Add all your authentication tokens as secrets. You will need to reference the name you give them here in your ''.yml'' file. A secret named ''PUBLISH_CURSEFORGE_TOKEN'' can be referenced using 
 <code yaml>  <code yaml> 
 ${{ secrets.PUBLISH_CURSEFORGE_TOKEN }} ${{ secrets.PUBLISH_CURSEFORGE_TOKEN }}
Line 173: Line 173:
 ==== Full .yml example ==== ==== Full .yml example ====
 <code yaml> <code yaml>
-name: Publish on GithubCurseforge & Modrinth    +name: Publish on GitHubCurseForge & Modrinth    
    
 on: [ pull_request, workflow_dispatch ]            on: [ pull_request, workflow_dispatch ]           
Line 214: Line 214:
         run: ./gradlew clean build         run: ./gradlew clean build
                  
-      - name: Publish (CurseForge/Modrinth/Github)+      - name: Publish (CurseForge/Modrinth/GitHub)
         uses: Kir-Antipov/mc-publish@v3.2                                            uses: Kir-Antipov/mc-publish@v3.2                                   
         with:         with:
Line 240: Line 240:
 To recap, here is what you should have by now: To recap, here is what you should have by now:
   * Newly generated authentication tokens for every platform    * Newly generated authentication tokens for every platform 
-  * Authentication tokens stored as secrets in your github repository+  * Authentication tokens stored as secrets in your GitHub repository
   * a ''.yml'' file in ''/.github/workflows'' pushed to your github repository   * a ''.yml'' file in ''/.github/workflows'' pushed to your github repository
   * a empty ''CHANGELOG.md'' file in your project root   * a empty ''CHANGELOG.md'' file in your project root
  
-If you have all these you are finished! You can now use your newly created Github Action to deploy updates for your mod!+If you have all these you are finished! You can now use your newly created GitHub Action to deploy updates for your mod!
  
 ===== Additional tips ===== ===== Additional tips =====
Line 266: Line 266:
 ==== Errors when uploading to Modrinth ==== ==== Errors when uploading to Modrinth ====
  
-Since Modrinth updated its API some people have problems uploading through the API. If that happens to you, try separating the modrinth portion from Github and Curseforge. You can do this easily by copying the MC-Publish step and trimming out the now unecessary input in ''with''. You should now have two separate steps.+Since Modrinth updated its API some people have problems uploading through the API. If that happens to you, try separating the Modrinth portion from GitHub and CurseForge. You can do this easily by copying the MC-Publish step and trimming out the now unnecessary input in ''with''. You should now have two separate steps.
  
 Change the version in the step that publishes to modrinth to 2.1 -> ''uses: Kir-Antipov/mc-publish@v2.1'' Change the version in the step that publishes to modrinth to 2.1 -> ''uses: Kir-Antipov/mc-publish@v2.1''
  
  
tutorial/publishing_mods_using_github_actions.txt · Last modified: 2023/04/10 09:04 by poopooracoocoo