surf-build

library2.0.0jsnpmunverified

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.

devops

npm install surf-build

github ↗package ↗

INSTALL

IMPORT

SIG · SURF-BUILD

surf-build

devopsjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

surf-build CLI

✓ npm install -g surf-build

✗ import { surfBuild } from '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

✓ npm install -g surf-build

✗ const surfRun = require('surf-build/run')

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

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.");

surf-build --version

Debug

Known issues

breakingThe `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.

affects: >=2.0.0

gotchaSurf 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.

affects: >=1.0.0

gotchaSurf 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.

affects: >=1.0.0

gotchaSurf 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

'surf-run' is not recognized as an internal or external command, operable program or batch file.

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.

`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

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'

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

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/surf-build/surf ↗

packagehttps://www.npmjs.com/package/surf-build ↗