{"id":15486,"library":"surf-build","title":"Surf Build Server","description":"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.","status":"abandoned","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/surf-build/surf","tags":["javascript","build","ci"],"install":[{"cmd":"npm install surf-build","lang":"bash","label":"npm"},{"cmd":"yarn add surf-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add surf-build","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { surfBuild } from 'surf-build'","symbol":"surf-build CLI","correct":"npm install -g surf-build"},{"note":"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`.","wrong":"const surfRun = require('surf-build/run')","symbol":"surf-run CLI","correct":"npm install -g surf-build"}],"quickstart":{"code":"// Ensure Node.js is installed. This package is primarily a global CLI tool.\n// As this package is effectively abandoned, consider modern alternatives for CI/CD.\n\n// 1. Install Surf globally via npm:\n// npm install -g surf-build\n\n// 2. Obtain a GitHub Personal Access Token.\n// Go to https://github.com/settings/tokens, generate a new token with 'repo' scope.\n\n// 3. Set the GITHUB_TOKEN environment variable.\n// This is crucial for 'surf-run' to interact with GitHub.\n// For Linux/macOS:\n// export GITHUB_TOKEN='YOUR_GITHUB_PERSONAL_ACCESS_TOKEN'\n// For Windows (Command Prompt):\n// set GITHUB_TOKEN=YOUR_GITHUB_PERSONAL_ACCESS_TOKEN\n// For Windows (PowerShell):\n// $env:GITHUB_TOKEN='YOUR_GITHUB_PERSONAL_ACCESS_TOKEN'\n\n// 4. Start the Surf build server (surf-run) to monitor your repositories:\n// surf-run\n// This command will continuously poll GitHub for new commits in your configured repositories\n// (if any, otherwise it monitors for any repo it has access to).\n\n// 5. Alternatively, perform a one-off build for a specific commit using 'surf-build':\n// Replace with your repository URL and a specific commit SHA.\n// surf-build --repo https://github.com/surf-build/surf --sha 6dadf3bd5744861300eff3b640146c1cb473970f\n\nconsole.log(\"Surf CLI commands executed. Check your terminal for build output and server status.\");\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project is hosted on GitHub. If not, consider migrating to a different CI solution that supports your chosen VCS/hosting platform.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install -g surf-build` to install the package globally. Verify your PATH includes the npm global executable directory.","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.","error":"'surf-run' is not recognized as an internal or external command, operable program or batch file."},{"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).","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.","error":"Error: No GITHUB_TOKEN environment variable set. Surf requires a token to interact with GitHub."},{"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.","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.","error":"Build failed: exit code 1"},{"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`.","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.","error":"Error: Not Found - no such file or directory, open '.../package.json'"}],"ecosystem":"npm"}