Philipp Horstenkamp
de6b54abe9
All checks were successful
Lint / pre-commit Linting (push) Successful in 1m38s
Reviewed-on: #53
111 lines
4.1 KiB
Markdown
111 lines
4.1 KiB
Markdown
# 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 |
|