{"id":13235,"library":"github-build","title":"Github Build Checks","description":"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.","status":"maintenance","version":"1.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/siddharthkp/github-build","tags":["javascript","github","build","checks","ci"],"install":[{"cmd":"npm install github-build","lang":"bash","label":"npm"},{"cmd":"yarn add github-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add github-build","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"HTTP client for making requests to the GitHub API.","package":"axios","optional":false}],"imports":[{"note":"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.","wrong":"import Build from 'github-build'","symbol":"Build","correct":"const Build = require('github-build')"}],"quickstart":{"code":"const Build = require('github-build');\n\n// It's crucial to use environment variables for sensitive tokens in production.\n// Replace with actual values from your CI/GitHub Actions environment.\nconst GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? '';\nconst REPO_SLUG = process.env.GITHUB_REPOSITORY ?? 'siddharthkp/github-build'; // e.g., 'owner/repo'\nconst COMMIT_SHA = process.env.GITHUB_SHA ?? '6954e71d46be1ae9b0529aae6e00b64d7a1023d4'; // Use actual commit SHA\n\nif (!GITHUB_TOKEN) {\n  console.error('GITHUB_TOKEN environment variable is not set. Cannot report build status.');\n  process.exit(1);\n}\n\nconst data = {\n  repo: REPO_SLUG,\n  sha: COMMIT_SHA,\n  token: GITHUB_TOKEN,\n  label: 'My Custom CI',\n  description: 'Running lint and tests...', // Description shown on GitHub\n  url: 'http://my-ci-service.com/builds/current-run-id', // Link to your CI run details\n};\n\nconst build = new Build(data);\n\nasync function runBuildProcess() {\n  console.log('Starting build status on GitHub...');\n  await build.start(); // Set status to 'pending'\n\n  try {\n    // Simulate actual build/test process\n    console.log('Simulating build/test for 3 seconds...');\n    await new Promise(resolve => setTimeout(resolve, 3000));\n    const testsPassed = Math.random() > 0.3; // Simulate success or failure randomly\n\n    if (testsPassed) {\n      console.log('Tests passed. Setting status to success.');\n      await build.pass(); // Set status to 'success' ✅\n    } else {\n      console.log('Tests failed. Setting status to failure.');\n      await build.fail(); // Set status to 'failure' ❌\n    }\n  } catch (error) {\n    console.error('An unexpected error occurred during the build process:', error);\n    await build.error(); // Set status to 'error' 🛑\n  } finally {\n    console.log('Build status update complete.');\n  }\n}\n\nrunBuildProcess();","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade to `github-build@1.2.4` or newer immediately to ensure the patched `axios` version is used and mitigate potential security risks.","message":"The 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.","severity":"breaking","affected_versions":"<1.2.4"},{"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.","message":"Authentication 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `const Build = require('github-build')` to ensure correct module loading, especially in environments where ESM interoperability is not guaranteed or configured.","message":"The `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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The provided GitHub token is either invalid, expired, or lacks the necessary permissions (e.g., `repo:status` scope) to set commit statuses.","error":"Failed to create status: 401 Unauthorized"},{"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.","cause":"The repository slug (e.g., `owner/repo`) or the commit SHA provided in the `data` object is incorrect or does not exist on GitHub.","error":"Failed to create status: 404 Not Found"},{"fix":"Change your import statement to `const Build = require('github-build')` to correctly load the CommonJS constructor.","cause":"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.","error":"TypeError: Build is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}