Surf Build Server

2.0.0 · abandoned · verified Tue Apr 21

Surf is a minimalist, multi-platform, language-agnostic build server designed specifically for GitHub. It aims to simplify continuous integration by integrating directly with Git and GitHub workflows, supporting builds even without webhooks or complex firewall configurations (requiring only outgoing HTTP requests). The package, `surf-build` (version 2.0.0), provides both the `surf-run` server component and the `surf-build` command-line tool. It differentiates itself from more feature-rich CI solutions like Jenkins by offering a simple, opinionated approach. It automatically detects and builds projects using common tools (Node.js, Rust, .NET, Autotools, CMake, Xcode) or executes custom scripts (`build.sh`, `script/ci`). It lacks a dedicated UI, a plugin ecosystem, and does not support version control systems other than Git/GitHub.

Common errors

```
'surf-run' is not recognized as an internal or external command, operable program or batch file.
```
cause The `surf-build` package, which includes `surf-run`, was not installed globally, or the global npm bin directory is not in your system's PATH.

fix Run `npm install -g surf-build` to install the package globally. Verify your PATH includes the npm global executable directory.
```
Error: No GITHUB_TOKEN environment variable set. Surf requires a token to interact with GitHub.
```
cause `surf-run` requires a GitHub Personal Access Token to be set as an environment variable named `GITHUB_TOKEN` to authenticate with GitHub's API.

fix Set the `GITHUB_TOKEN` environment variable before running `surf-run`. Example: `export GITHUB_TOKEN='YOUR_TOKEN_HERE'` (Linux/macOS) or `set GITHUB_TOKEN=YOUR_TOKEN_HERE` (Windows CMD).
```
Build failed: exit code 1
```
cause The custom build script (e.g., `build.sh`, `script/ci`) or one of Surf's auto-detected build steps (like `npm test` for Node.js) exited with a non-zero status code, indicating a failure.

fix Review the preceding terminal output for error messages from your build script or the underlying build tools (e.g., `npm`, `cargo`, `msbuild`). Debug your project's build process locally.
```
Error: Not Found - no such file or directory, open '.../package.json'
```
cause Surf attempted to perform a Node.js specific build (e.g., `npm install && npm test`), but no `package.json` file was found in the repository's root, or the repository was not properly checked out.

fix Ensure your repository has a `package.json` in its root if you expect a Node.js build. Verify the `--repo` and `--sha` parameters are correct for `surf-build`.

Warnings

breaking The `surf-build` package and the Surf project appear to be abandoned. The last stable version (2.0.0) was published over 7 years ago (as of April 2026), indicating a severe lack of ongoing development, maintenance, and security updates. It is highly recommended to seek modern, actively maintained CI/CD solutions.
Fix: Migrate to a currently maintained CI/CD platform such as GitHub Actions, GitLab CI/CD, Jenkins, CircleCI, or Travis CI. Evaluate alternatives based on your project's specific needs for features, support, and community.
gotcha Surf is exclusively designed for Git and GitHub. It does not provide support for other version control systems (e.g., Subversion, Mercurial) or other Git hosting platforms (e.g., Bitbucket, GitLab CE). Projects using non-GitHub VCS will not work.
Fix: Ensure your project is hosted on GitHub. If not, consider migrating to a different CI solution that supports your chosen VCS/hosting platform.
gotcha Surf operates purely as a command-line tool and does not offer a graphical user interface (UI) or a dashboard for monitoring builds, configuring settings, or reviewing logs in a browser. All interactions and feedback are via the terminal.
Fix: Developers must rely on terminal output and potentially external logging tools for build monitoring. If a UI is critical, consider alternatives like Jenkins or CircleCI.
gotcha Surf lacks a plugin architecture or an active community, severely limiting its extensibility. It supports a predefined set of project types and custom shell/batch scripts, but complex integrations or specialized build steps may be challenging or impossible to implement.
Fix: For projects requiring extensive customization, integrations with various tools, or a rich ecosystem of plugins, a more robust and extensible CI system is recommended.
gotcha The `surf-run` command requires a `GITHUB_TOKEN` environment variable to be set for proper interaction with GitHub. Failure to set this token will prevent the server from polling repositories or reporting build statuses.
Fix: Before running `surf-run`, ensure the `GITHUB_TOKEN` environment variable is correctly set with a valid GitHub Personal Access Token (PAT) that has appropriate repository permissions.

Install

npm install surf-build npm
yarn add surf-build yarn
pnpm add surf-build pnpm

Imports

surf-build CLI
wrong:
```
import { surfBuild } from 'surf-build'
```
correct:
```
npm install -g surf-build
```
The `surf-build` package is primarily designed as a global command-line interface (CLI) tool. It does not expose a public programmatic API for direct import into other JavaScript/TypeScript applications. Attempts to `import` or `require` modules from `surf-build` are not supported and are likely to fail or lead to unstable behavior due to its internal structure and lack of API documentation.
surf-run CLI
wrong:
```
const surfRun = require('surf-build/run')
```
correct:
```
npm install -g surf-build
```
Similar to `surf-build`, the `surf-run` command is a global CLI executable provided by the `surf-build` package. It is intended to be run directly from the terminal after global installation. There is no documented or supported programmatic entry point for `surf-run`.

Quickstart

Demonstrates the global installation of `surf-build` and the command-line usage of `surf-run` (the build server) and `surf-build` (the one-off builder), including setting the necessary GitHub access token.

// Ensure Node.js is installed. This package is primarily a global CLI tool.
// As this package is effectively abandoned, consider modern alternatives for CI/CD.

// 1. Install Surf globally via npm:
// npm install -g surf-build

// 2. Obtain a GitHub Personal Access Token.
// Go to https://github.com/settings/tokens, generate a new token with 'repo' scope.

// 3. Set the GITHUB_TOKEN environment variable.
// This is crucial for 'surf-run' to interact with GitHub.
// For Linux/macOS:
// export GITHUB_TOKEN='YOUR_GITHUB_PERSONAL_ACCESS_TOKEN'
// For Windows (Command Prompt):
// set GITHUB_TOKEN=YOUR_GITHUB_PERSONAL_ACCESS_TOKEN
// For Windows (PowerShell):
// $env:GITHUB_TOKEN='YOUR_GITHUB_PERSONAL_ACCESS_TOKEN'

// 4. Start the Surf build server (surf-run) to monitor your repositories:
// surf-run
// This command will continuously poll GitHub for new commits in your configured repositories
// (if any, otherwise it monitors for any repo it has access to).

// 5. Alternatively, perform a one-off build for a specific commit using 'surf-build':
// Replace with your repository URL and a specific commit SHA.
// surf-build --repo https://github.com/surf-build/surf --sha 6dadf3bd5744861300eff3b640146c1cb473970f

console.log("Surf CLI commands executed. Check your terminal for build output and server status.");

view raw JSON →