# screeps-deploy-action

## Introduction

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:

```yaml
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:
1.  **Zero-configuration at Runtime:** By bundling everything, the action runner doesn't need to run `npm install`, which speeds up the action execution.
2.  **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.
3.  **Standard Practice:** This is a recommended practice for JavaScript-based GitHub/Gitea Actions.

### The Tool: @vercel/ncc

We chose [`@vercel/ncc`](https://github.com/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:

```bash
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 |