This GitHub Action facilitates the uploading of code to a Screeps server. It's designed to automate the process of deploying JavaScript code to your Screeps account, ensuring that your game logic is consistently and efficiently updated. Prerequisites

A Screeps account with an access token.
A GitHub or Gitea repository with your Screeps code.

Usage

To use this action, you need to set it up in your workflow .yml file located in the .github/workflows directory of your repository.

Inputs

protocol: The protocol to use (default: https).
hostname: The hostname of the Screeps server (default: screeps.com).
port: The port to use (default: 443).
path: The path for the API (default: /).
token: Authentication token for Screeps.
username: Username for Screeps account (used if no token is provided).
password: Password for Screeps account (used if no token is provided).
prefix: Directory prefix for file paths.
pattern: Glob pattern to match files (default: *.js).
branch: Branch in Screeps to which the code will be uploaded (default: default).
git-replace: Overwrite "{{gitRef}}", "{{gitHash}}" and "{{deployTime}}" values in files matching the pattern.

Example Workflow

Create a .yml file (e.g., screeps-deploy.yml) in your repository's .github/workflows directory or .gitea/workflows directory:

name: Deploy to Screeps

on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v2

    - name: Upload to Screeps
      uses: Screeps/screeps-deploy-action@main
      with:
        token: ${{ secrets.SCREEPS_TOKEN }}
        pattern: '**/*.js'
        branch: 'default'
        git-replace: /some_options.js

In this example:

The action runs on every push to the repository.
It checks out your code.
Then, it uses the "Upload to Screeps" action to deploy the code to your Screeps account.
You need to set SCREEPS_TOKEN in your repository secrets.

Advanced Usage

Please note that you can easily filter your deployment branches in the push action. Multiple deploy steps or jobs are recomended for mulitple deployments.

Development & Build

This project includes a build step to prepare the action for use.

Why a Build Step?

We use a build step to compile the JavaScript code and its dependencies into a single, self-contained file (dist/index.js). This approach is chosen for the following reasons:

Zero-configuration at Runtime: By bundling everything, the action runner doesn't need to run npm install, which speeds up the action execution.
Reliability: It guarantees that the exact versions of dependencies tested during development are used in the action, avoiding potential issues with version updates or missing packages.
Standard Practice: This is a recommended practice for JavaScript-based GitHub/Gitea Actions.

The Tool: @vercel/ncc

We chose @vercel/ncc as the compiler because:

It is designed specifically for compiling Node.js modules into a single file.
It handles native dependencies and dynamic requires intelligently.
It is zero-config, making the setup simple and maintainable.

How to Build

If you modify index.js or change dependencies, you must rebuild the project before committing:

npm install
npm run build

This will update the dist/index.js file, which should be committed to the repository.

Cross-Platform Compatibility

To ensure this action runs on all platforms (including ARM devices like Raspberry Pi), we explicitly exclude optional native dependencies (utf-8-validate and bufferutil) from the build. This forces the underlying ws library to use its pure JavaScript fallback implementation.

Build Protocol

Metric	Status / Value
Last Build	Saturday, December 27, 2025
Build Tool	`@vercel/ncc`
Target Runtime	Node.js 20
Artifact	`dist/index.js` (Self-contained)
Native Binaries	None (Excluded for cross-platform support)
Compatibility	Linux (x64/ARM), Windows, macOS
Build Status	✅ Success