contributors-please

Incremental, path-aware contributor recognition for repositories that want a generated CONTRIBUTORS.md without losing maintainer edits.

The package contains the reusable engine and CLI used by smorinlabs/contributors-please-action.

Install

npm install -g [email protected]
contributors-please --version

CLI

Bootstrap state and render contributors:

npx contributors-please@1 init \
  --non-interactive \
  --owner smorinlabs \
  --repo example \
  --config-file .contributors.yml

Render from an existing state file:

contributors-please render --config-file .contributors.yml

Validate configuration:

contributors-please validate --config-file .contributors.yml

Library API

The stable entrypoint is the package root:

import {
  Contributors,
  GitHubClient,
  PathClassifier,
  VERSION,
  readStateFile,
  writeStateFile,
  mergeState,
  render,
  parseTemplate,
} from "contributors-please";

Contributors.fromConfigFile() loads .contributors.yml and state from disk, then separates read-only computation from side effects:

const github = await GitHubClient.create({
  owner: "smorinlabs",
  repo: "example",
  token: process.env.GITHUB_TOKEN,
});

const contributors = await Contributors.fromConfigFile(github, {
  configFile: ".contributors.yml",
  dryRun: true,
});

const result = await contributors.run();

// Commits to the current branch. Defaults to the message
// "docs: update contributors" with a "[skip ci]" trailer appended;
// pass skipCi: false to omit the trailer, or message to override.
await contributors.commit({});

// Opens a pull request. Defaults to the commit message
// "docs: update contributors" with NO "[skip ci]" trailer; pass
// skipCi: true to append it, or commitMessage to override.
await contributors.openPullRequest({
  branch: "contributors-please/update",
  base: "main",
  title: "docs: update contributors",
  body: "Generated by contributors-please.",
});

const check = await contributors.check();

[skip ci] and required status checks

The two entry points default differently on purpose:

• commit() appends [skip ci] by default. A bookkeeping commit pushed straight to the default branch rarely needs a CI run, and the trailer guards against workflow loops.
• openPullRequest() omits [skip ci] by default. The trailer suppresses all push/pull_request workflow triggers on the PR's head commit, so if the base branch has required status checks backed by those workflows, the checks never report and the PR is permanently stuck at "Expected — waiting for status to be reported". Only set skipCi: true here if the base branch has no required status checks.

The same applies to a custom message/commitMessage that contains [skip ci] (or any equivalent trailer). For loop protection in pull-request flows, prefer paths-ignore on the generated files in the calling workflow instead of [skip ci].

Semver Contract

From 1.0.0 forward, the package root export surface is covered by semver.

• Patch releases contain bug fixes with no API changes.
• Minor releases may add exports, optional parameters, or optional fields while keeping existing call sites compiling.
• Major releases may include breaking changes and must document migration notes.

Deep imports such as contributors-please/dist/engine/... are not stable API.

Release Setup

Tags matching v*.*.* run the publish workflow. The package is published by npm Trusted Publishing from workflow publish.yml in GitHub environment npm; the workflow uses id-token: write and does not require NPM_TOKEN.

• RELEASE_PLEASE_CLIENT_ID (preferred) or RELEASE_PLEASE_APP_ID (deprecated), together with RELEASE_PLEASE_PRIVATE_KEY: credentials for the release-please GitHub App. publish.yml mints a short-lived installation token from them, scoped to smorinlabs/contributors-please-action with contents: write, and uses it to (1) check out the action repo for the action-output consistency check and (2) send the contributors-please-released repository dispatch that notifies the action repo of a release. The dispatch token is preflighted before npm publish, so missing credentials fail the run before anything is published.
• CONTRIBUTORS_PLEASE_ACTION_TOKEN: optional fallback token used only when the App token above is unavailable. To send the release dispatch it needs contents: write on smorinlabs/contributors-please-action; the cross-repo checkout additionally falls back to github.token.
• CONTRIBUTORS_PLEASE_ACTION_REF: optional repository variable selecting the action repository ref used for the action-output consistency check. It defaults to main.

GitHub Enterprise

Pass serverUrl, apiUrl, or graphqlUrl to GitHubClient.create() when a GitHub Enterprise deployment uses non-default paths. GHE no-reply domains can also be configured in .contributors.yml with no_reply_domain.