Registry / devops / github-build

github-build

JSON →
library1.2.4jsnpmunverified

The `github-build` library provides a minimalist interface for setting GitHub Commit Statuses (also known as "Checks" or "Build Statuses") via the GitHub API. It enables continuous integration (CI) services to report the status of builds, tests, and other automated checks directly on pull requests and commits within GitHub. The current stable version is `1.2.4`, primarily focused on stability and security. Its release cadence appears to be low, with releases often addressing specific issues like security patches. Key differentiators include its straightforward API for managing `pending`, `success`, `failure`, and `error` states, making it easy to integrate into CI pipelines without dealing directly with the complexities of the GitHub REST API for status updates. It's designed for simple, direct status reporting rather than comprehensive GitHub API interaction.

npm install github-build
INSTALL
IMPORT
SIG · GITHUB-BUILD
G
github-build
devopsjavascriptv1.2.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

Build
const Build = require('github-build')
import Build from 'github-build'
This library is primarily a CommonJS module. While modern Node.js might support some interoperability, using `require` is the safest and intended way to import the `Build` constructor.

This quickstart demonstrates how to initialize `github-build` and use its methods (`start`, `pass`, `fail`, `error`) to update a GitHub commit status for a CI job, including secure token handling for sensitive credentials.

const Build = require('github-build'); // It's crucial to use environment variables for sensitive tokens in production. // Replace with actual values from your CI/GitHub Actions environment. const GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? ''; const REPO_SLUG = process.env.GITHUB_REPOSITORY ?? 'siddharthkp/github-build'; // e.g., 'owner/repo' const COMMIT_SHA = process.env.GITHUB_SHA ?? '6954e71d46be1ae9b0529aae6e00b64d7a1023d4'; // Use actual commit SHA if (!GITHUB_TOKEN) { console.error('GITHUB_TOKEN environment variable is not set. Cannot report build status.'); process.exit(1); } const data = { repo: REPO_SLUG, sha: COMMIT_SHA, token: GITHUB_TOKEN, label: 'My Custom CI', description: 'Running lint and tests...', // Description shown on GitHub url: 'http://my-ci-service.com/builds/current-run-id', // Link to your CI run details }; const build = new Build(data); async function runBuildProcess() { console.log('Starting build status on GitHub...'); await build.start(); // Set status to 'pending' try { // Simulate actual build/test process console.log('Simulating build/test for 3 seconds...'); await new Promise(resolve => setTimeout(resolve, 3000)); const testsPassed = Math.random() > 0.3; // Simulate success or failure randomly if (testsPassed) { console.log('Tests passed. Setting status to success.'); await build.pass(); // Set status to 'success' ✅ } else { console.log('Tests failed. Setting status to failure.'); await build.fail(); // Set status to 'failure' ❌ } } catch (error) { console.error('An unexpected error occurred during the build process:', error); await build.error(); // Set status to 'error' 🛑 } finally { console.log('Build status update complete.'); } } runBuildProcess();
Debug
Known issues
breakingThe library relies on `axios`, which had a critical vulnerability (CVE-2023-45857) affecting versions prior to `1.6.0`. While `github-build` version `1.2.4` addresses this by bumping `axios` to `1.6.0`, older versions of `github-build` might expose applications to HTTP request smuggling or other related issues if not updated.
fix
Upgrade to `github-build@1.2.4` or newer immediately to ensure the patched `axios` version is used and mitigate potential security risks.
affects: <1.2.4
gotchaAuthentication requires a GitHub OAuth token with appropriate permissions. For classic Personal Access Tokens (PATs), the `repo:status` scope is necessary. For GitHub Apps, the app must have 'Commit statuses' read and write permissions. Incorrectly scoped or expired tokens will result in API authentication failures.
fix
Generate a GitHub token with the minimum required `repo:status` scope (for PATs) or ensure your GitHub App has 'Commit statuses' read and write permissions. Always verify the token's validity and expiration.
affects: >=1.0.0
gotchaThe `github-build` library primarily uses CommonJS `require` syntax. Attempting to import it using ES Modules `import` syntax (`import Build from 'github-build'`) in certain environments (e.g., older Node.js versions or without proper bundler configuration) may lead to runtime errors due to the lack of explicit ESM exports in the package's `package.json`.
fix
Always use `const Build = require('github-build')` to ensure correct module loading, especially in environments where ESM interoperability is not guaranteed or configured.
affects: >=1.0.0
Errors
Common errors & fixes
Failed to create status: 401 Unauthorized
The provided GitHub token is either invalid, expired, or lacks the necessary permissions (e.g., `repo:status` scope) to set commit statuses.
fix
Verify your `GITHUB_TOKEN` is correct and active. Ensure it has the `repo:status` scope or equivalent permissions for GitHub Apps. Re-generate if necessary.
Failed to create status: 404 Not Found
The repository slug (e.g., `owner/repo`) or the commit SHA provided in the `data` object is incorrect or does not exist on GitHub.
fix
Double-check the `repo` and `sha` values passed to the `Build` constructor. Confirm the repository exists and the commit SHA is valid and accessible.
TypeError: Build is not a constructor
This error typically occurs when attempting to import `github-build` using ES Modules `import Build from 'github-build'` syntax, but the module is a CommonJS export and isn't being correctly resolved as a default export.
fix
Change your import statement to `const Build = require('github-build')` to correctly load the CommonJS constructor.
Upgrade
Version history
1.2.4latest on npm
Audit
Dependencies
axiosrequiredHTTP client for making requests to the GitHub API.
Agent activity
2 hits · last 30 days
node
2
Resources
github-build — npm install github-build · libregistry