First-party release automation

Turn a GitHub Release into a ready-to-download PalMods file.

Build your mod once. The official action creates the archive, carries over your release notes, uploads it to PalMods, waits for scanning, and leaves a complete job summary in GitHub.

Create a publish token View the action

Production canary verified with palmods/palmods-publish@v1

Mod-scoped accessOne token, one mod

Repeatable archivesDeterministic directory packaging

Retry-safe jobsReruns resume the same submission

Four-step setup

Connect the repository once. Release from GitHub after that.

The mod page stays in your control. Automation only creates and processes release files for the mod bound to its token.

Create a publish token

Bind one short-lived credential to one PalMods mod.

Describe the release

Map build output to PalMods metadata in .palmods.yml.

Add the workflow

Build from the immutable tag and run the first-party action.

Publish a GitHub Release

Release notes, files, scanning, and status now travel together.

Before you begin

Prepare a private test path first.

Create the PalMods mod page before issuing a token. You may keep the mod as a draft while you validate the workflow, so a test file never becomes public.

You own or co-author the target mod.
Your build produces a release directory or ZIP.
You can add repository secrets and workflows.

Authenticate GitHub

Create a token that can publish to only one mod.

Use a PalMods publish token in CI. Never give GitHub your account session, password, or a general-purpose access token.

1
Open Developer settings
Sign in to PalMods, open Settings, and select the Developer tab.
2
Create a publish token
Choose the mod, give the token a recognizable repository name, and choose a rotation window. PalMods displays the secret once.
3
Store it in GitHub
Open the repository's Settings → Secrets and variables → Actions page and add a repository secret named PALMODS_PUBLISH_TOKEN.

Treat the value as a password.

Never place it in workflow YAML, source, release notes, screenshots, artifacts, or a committed environment file. If it appears anywhere public, revoke it and create a replacement.

Describe the artifact

Add one small .palmods.yml file.

The configuration tells the action what to package and tells PalMods how the resulting file should be labeled.

.palmods.yml

schema: 1
mod: aqua-circuit

files:
  - path: build/palmods
    archive_name: aqua-circuit-${version}.zip
    category: main
    loader: lua
    side: both
    game_versions:
      - '1.0'

mod

Target mod

Use the slug from the PalMods URL. It must match the token's bound mod.

path

Build output

Point to a directory or existing ZIP inside the checked-out workspace.

archive_name

Download name

End with .zip. The ${version} placeholder uses the normalized release tag.

category / loader / side

Install metadata

Choose values that match the archive users will actually install.

game_versions

Tested compatibility

List only the Palworld versions you tested with the final archive.

channel

Optional override

Omit it to map stable releases to release and GitHub prereleases to beta.

Add up to ten independent entries under filesfor client, server, or optional archives. Each entry receives its own upload and PalMods job. JSON is also supported through the action's config input.

Run on release

Build from the tag, then call the official action.

The workflow below triggers only when you publish a GitHub Release. Replace the build command with the command that creates the path in .palmods.yml.

.github/workflows/publish-palmods.yml

name: Publish to PalMods

on:
  release:
    types: [published]

permissions:
  contents: read

concurrency:
  group: palmods-release-${{ github.event.release.id }}
  cancel-in-progress: false

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the release tag
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.release.tag_name }}
          persist-credentials: false

      - name: Build the release directory
        run: ./scripts/build-release.sh

      - name: Publish to PalMods
        id: palmods
        uses: palmods/palmods-publish@v1
        with:
          token: ${{ secrets.PALMODS_PUBLISH_TOKEN }}

Check out the release tag

The runner builds the commit the author released, not a newer default-branch commit.

Keep permissions read-only

The action does not need write access to repository contents. The PalMods token supplies its separate, narrow permission.

Serialize the release

The concurrency key prevents overlapping attempts for the same GitHub Release while still allowing safe reruns.

Choose your pinning policy.

@v1 follows reviewed, compatible v1 releases. Security-sensitive repositories can pin the full commit SHA from the verified action release .

Ship the first version

Publish a GitHub Release and follow one job summary.

GitHub remains the place where you choose the tag, write release notes, and decide whether a version is stable or prerelease.

Release checklist

Commit the workflow and .palmods.yml to the default branch.
Test the exact build command from a clean checkout.
Create a tag such as v1.4.0.
Write the changelog in the GitHub Release body.
Publish the release and open the Actions run.

What PalMods receives

Git tag: v1.4.0 → 1.4.0
Release body: Changelog Markdown
Stable release: release channel
Prerelease: beta channel by default

A successful action run means PalMods reached a safe terminal state.

ready and warning succeed. rejected, failed, and expired fail after the action writes links and details to the job summary.

After you click Publish

The archive moves through the normal PalMods safety pipeline.

Automation changes the submission surface, not the review standard. Mod visibility and page settings are never changed by the action.

01 · Package

Build once

Use an existing ZIP or let the action create a deterministic archive from a directory.

02 · Authorize

Open one job

The token is checked against the target mod before PalMods allocates an upload.

03 · Upload

Send the archive

The file goes directly to its signed storage destination; the token does not.

04 · Verify

Run safety checks

PalMods applies the same configured virus and package checks as a website upload.

05 · Report

Finish in GitHub

The job summary links to every PalMods job and records its final state.

Safe to rerun

A failed runner does not have to create a second file.

Repository ID, GitHub Release ID, and archive name form the stable submission identity. Retryable requests resume that identity; changed metadata requires a new release.

Security defaults

The action is deliberately narrow about credentials, files, and destinations.

Token stays on the API origin

It is masked before processing and is never sent to the signed storage upload URL.

Redirects are rejected

API and storage redirects cannot forward credentials or signed headers to an unexpected host.

Paths stay in the workspace

Config and artifact paths cannot escape the checkout, and the repository root cannot be packaged.

Unsafe entries are refused

Directory packaging rejects symbolic links, sockets, devices, and other non-regular files.

Found a publishing security issue? Use the repository's private security reporting guidance . Never include a real token or signed upload URL in a public issue.

Troubleshooting

Start with the machine-readable code in the job summary.

Every submitted file includes a durable PalMods job link. Preserve that job ID when asking for support.

Error	What it means	What to do
`invalid_token / expired_token`	The secret is missing, revoked, malformed, or past its expiry.	Check the secret name. If the one-time value is unavailable, create a replacement token and update GitHub.
`mod_access_denied`	The token cannot publish to the configured mod.	Verify the mod slug, token binding, and current owner or co-author access.
`invalid_package_metadata`	A loader, side, category, channel, or game version is not accepted.	Compare .palmods.yml with the fields below and the packaging contract.
`idempotency_conflict`	This GitHub Release and logical file were already submitted with different metadata.	Publish a new release tag after changing the archive or its metadata.
`Timed out while scanning`	GitHub stopped waiting, but the durable PalMods job is still running.	Rerun the failed job. The action resumes the existing submission instead of creating a duplicate.

Ready to connect a repository?

Create the scoped token, then ship the next release from GitHub.

Start with a draft mod if you want a private end-to-end test before publishing to users.

Create a publish token Review packaging

Create a publish token

Describe the release

Add the workflow

Publish a GitHub Release

Prepare a private test path first.

Open Developer settings

Create a publish token

Store it in GitHub

Target mod

Build output

Download name

Install metadata

Tested compatibility

Optional override

Check out the release tag

Keep permissions read-only

Serialize the release

Build once

Open one job

Send the archive

Run safety checks

Finish in GitHub

A failed runner does not have to create a second file.

Token stays on the API origin

Redirects are rejected

Paths stay in the workspace

Unsafe entries are refused

Create the scoped token, then ship the next release from GitHub.