8.2. Automatically Updating Nexus From GitHub

Uploading to Nexus Automatically

The goal of this page is to help you automatically upload your mod to Nexus when you create a release on GitHub, without actually having to go to Nexus and manually create it. This tutorial assumes a couple of things about your mods setup. If your setup doesn't fit these assumptions, you can still use this as a base to figure out how to make it work for your structure, but you may need to ask for help

1. It assumes that you've got 1 mod per repository.
2. It assumes that you're uploading 1 file to Nexus per repository.
3. It assumes that you want to create GitHub Release to upload your mod.

Setup

To get started, you'll need to fetch your API Key from Nexus and put it into an "environment" in GitHub. Please note that your API key basically allows whoever has it to do actions against your account on Nexus, so make sure to keep it secret and never pass it around.

Creating your environment

In your GitHub repository, go to the Settings for that repository, and on the left click "Environments". At the top-right of that page, you'll want to click "New environment" and create an environment called NEXUS_UPLOAD. You can call it something else, but if you do, make sure to edit the workflow script below to match it.

Getting your API key

On Nexus, go to Site Settings -> API Keys and scroll to the bottom of the page where you'll find a "Personal API Key" that you can either set up or copy.

Warning

While your API Key can be changed with the refresh button next to it on Nexus, it's still a secret that will allow anyone who has it to perform actions on your Nexus account. Be sure to keep this secret and don't give it out to anyone else.

Storing your key in GitHub

Go to your NEXUS_UPLOAD environment on GitHub and under "Environment secrets" click "Add environment secret". The name of this secret should ne NEXUS_TOKEN, and the value should be your API Key from Nexus.

Warning

Make sure that you add it to "Environment secrets" and not "Environment variables". Secrets are encrypted and protected during workflows, variables are not.

The Workflow

To get the automatic updates, add this file to your repository under .github/workflows/nexus_upload.yml. Towards the bottom, you'll need to manually adjust the file_group_id and display_name under the Upload to Nexus step.

name: Upload To Nexus

# This means that this workflow will only happen when you create a new release in the "Releases" section of your
# repository
on:
  release:
    types: [released]
  workflow_dispatch:

# This allows this workflow to upload your mod to the Release. If you don't want that, you can remove this bit as well
# as the "Upload mod to release" step
permissions:
  contents: write

jobs:
  Upload:
    runs-on: ubuntu-latest
    # This should match the environment name you've defined in "Settings -> Environments"
    environment: NEXUS_UPLOAD

    steps:
      # This checks out the repository to the current directory
      - uses: actions/checkout@v4
        with:
          submodules: true

      # This uses a tool called `jq` to look up the version of your mod from the `manifest.json` file, and puts it in
      # {{ env.VERSION }} to send to Nexus later
      - name: Extract version from manifest.json
        run: |
          VERSION=$(jq .version manifest.json -r)
          echo "VERSION=$VERSION" >> $GITHUB_ENV

      # This is the step that zips up the mod for uploading
      - name: Zip mod
        run: zip -r mod.zip ./*

      # Here we upload our file to Nexus
      - name: Upload to Nexus
        uses: Nexus-Mods/upload-action@v1.0.0-beta.4
        with:
          api_key: ${{ secrets.NEXUS_TOKEN }}
          file_group_id: "your_file_group_id"
          filename: mod.zip
          version: ${{ env.VERSION }}
          display_name: "Your Mod Name"

      # This is the step that also uploads the zip to the Release that we create
      - name: Upload mod to release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        shell: bash
        run: |
          gh release upload ${{ github.ref_name }} mod.zip

Releasing

On the right of your repository, you should have a "Releases" section. If you click into this, you'll be able to "Draft a new release". Once you Publish this release, the above action will trigger automatically and should zip up your mod and automatically upload it to Nexus