Upload Action

Quick start

Add the action to a workflow step after your build produces one or more .jar or .zip artifacts. The action uploads those files to Guizhan Resources and creates a new project version through the existing API.

Minimal example using a local file:

- uses: ybw0014/guizhan-resources-action@v1
  with:
    token: ${{ secrets.GUIZHAN_TOKEN }}
    project-id: my-project
    channel: releases
    files: build/libs/*.jar

Authentication

The action calls POST /v1/projects/{projectId}/versions on your behalf. Your token must include the project:version:create scope. Organization-owned projects also require the project:version:create organization member permission.

Create a token in your Guizhan Resources account settings and store it as a repository secret (for example, GUIZHAN_TOKEN). The action automatically masks the token in logs.

Reference

uses: ybw0014/guizhan-resources-action@v1

Inputs

domain

Default: `https://resources.guizhanss.com/api`

API base URL. A bare host such as resources.guizhanss.com is normalized to https://resources.guizhanss.com/api. Trailing slashes are removed.

token Required

Access token with project:version:create scope.

project-id Required

Project ID or slug.

channel Required

Channel ID or slug.

files Required

Default: none

Newline or comma-separated local paths or glob patterns. At least one of files or artifact-names is required.

artifact-names Required

Default: none

Newline or comma-separated GitHub Actions artifact names from the current workflow run. At least one of files or artifact-names is required.

primary-file

Default: none

Basename of the file that should be treated as the primary file. Must match one of the resolved files.

version

Default: `GITHUB_REF_NAME`

Version string. When omitted, the action derives it from GITHUB_REF_NAME and strips one leading v.

name

Default: resolved `version`

Display name for the version.

changelog

Default: omit

Changelog in Markdown.

minecraft-versions

Default: auto/omit

Comma or newline-separated Minecraft versions. Overrides auto-detection.

platforms

Default: auto/omit

Comma or newline-separated platform IDs. Overrides auto-detection.

dependencies

Default: omit

JSON string matching the API dependency format. Fails on invalid JSON.

auto-detect-minecraft

Default: `true`

Infer Minecraft versions from resolved file basenames when explicit input is omitted.

auto-detect-platform

Default: `true`

Infer platforms from JAR descriptors or basenames when explicit input is omitted.

Outputs

version-id

ID of the created version.

version-url

Direct URL to the created version page.

uploaded-files

Comma-separated list of uploaded file basenames in final order.

api-code

API response code.

Local file usage

Provide files as paths or glob patterns relative to the repository root. The action resolves globs, rejects directories, and validates file extensions and sizes against the API limits before uploading.

- uses: ybw0014/guizhan-resources-action@v1
  with:
    token: ${{ secrets.GUIZHAN_TOKEN }}
    project-id: my-project
    channel: releases
    files: |
      build/libs/plugin.jar
      build/distributions/docs.zip
    primary-file: plugin.jar
    version: ${{ github.ref_name }}
    changelog: ${{ github.event.release.body }}

Artifact usage

If your build step uploads artifacts with actions/upload-artifact, you can reference those artifact names instead of local paths. The action downloads artifacts from the current workflow run into a temporary directory and treats the contained files as upload sources.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./gradlew build
      - uses: actions/upload-artifact@v4
        with:
          name: plugin-artifact
          path: build/libs/*.jar

  upload:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: ybw0014/guizhan-resources-action@v1
        with:
          token: ${{ secrets.GUIZHAN_TOKEN }}
          project-id: my-project
          channel: releases
          artifact-names: plugin-artifact

You can combine files and artifact-names in the same step. Duplicate basenames across sources are rejected before upload.

Primary file behavior

The first entry in data.files becomes the primary file for the version. This is the file users receive when they click a generic download link. By default, files are sorted by basename then absolute path, so the order is deterministic.

If you want a specific file to be primary, set primary-file to its basename. The action moves that file to the first position in the upload list. primary-file must exactly match one of the resolved basenames.

Auto-detection behavior

When minecraft-versions or platforms are not provided explicitly, the action can infer them from the resolved files.

• Minecraft versions: Scans file basenames for patterns such as 1.20.4, 1.21, etc. Deduplicates matches and includes them when non-empty.
• Platforms: Inspects .jar files for paper-plugin.yml (Paper), plugin.yml (Bukkit), and checks basenames for folia, paper, or spigot. Deduplicates matches and includes them when non-empty.

Explicit inputs always override auto-detection. If detection finds nothing, the optional fields are omitted and the API falls back to the channel defaults.

Troubleshooting

| Error | Cause | Resolution | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | Validation failure. Common causes include invalid data JSON, missing required fields, unsupported file types, file count over the limit, or individual files exceeding the size limit. | Check that all required inputs are set, files are .jar or .zip, and file sizes are within limits. Verify dependencies is valid JSON if provided. | | 401 | Token is missing, expired, or invalid. | Confirm the token is stored correctly and has not expired. | | 403 | Token lacks the project:version:create scope, or the project is organization-owned and your account lacks the organization member permission. | Create a new token with the required scope, or ask the organization owner to grant the permission. | | 409 | A version with the same identifier already exists for this project and channel. | Change the version input or delete the existing version first. |

For transient network errors or HTTP 502/503/504, the action retries up to 3 times with exponential backoff starting at 500 ms. Validation and authentication errors are not retried.