npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@noldova/tools.pipelines.github

v0.0.23

Published

Runs the steps of `@noldova/tools.pipelines` on GitHub Actions. This version holds `pipelines`, the command line a workflow calls, with the source, archive, publish, nightly, prune, tag, toolchain, line-endings, unchanged, reproducible, dependents, pins,

Readme

@noldova/tools.pipelines.github

Runs the steps of @noldova/tools.pipelines on GitHub Actions. This version holds pipelines, the command line a workflow calls, with the source, archive, publish, nightly, prune, tag, toolchain, line-endings, unchanged, reproducible, dependents, pins, installed, build, test and timing steps, and the prune, tag, dependents and pins steps' access to GitHub.

Install

npm install @noldova/tools.pipelines.github

Use

In a workflow

A job installs the package at an exact version, without install scripts, and calls pipelines with a step's name and values in the checkout:

- run: npm install --global --ignore-scripts @noldova/[email protected]
- run: pipelines source "$VERSION" "$COMMIT"
- id: nightly
  run: |
    version="$(pipelines nightly "$COMMIT" https://registry.npmjs.org/)"
    echo "version=$version" >> "$GITHUB_OUTPUT"

| Step | Values | |---|---| | source | <version> <commit> | | archive | <folder> <version> <commit> <scope> | | publish | <folder> <version> <commit> <scope> <registry> <access> | | nightly | <commit> <registry> | | prune | <version> <commit> <scope> <registry> <keep-versions> | | tag | <version> <commit> | | toolchain | <node-version> [<npm-version>] | | line-endings | none | | unchanged | none | | reproducible | <folder> | | dependents | <version> <commit> | | pins | <version> <commit> | | relock | <repository> <request> <result file> [<lock file>=<npm script>...] | | installed | [<folder>] | | build | [--version <version>] [<package>...], or --list-copies | | test | [--skip-test-details] [--skip-coverage-details] [<filter>...] | | timing | none |

@noldova/tools.pipelines's README says what each step checks and does. The reproducible, dependents and pins steps make their temporary folders in RUNNER_TEMP, which the runner empties after each job, cancelled ones included.

  • A step that succeeds writes its message to standard output and exits with code 0; an empty message, such as the nightly step's when nothing changed, writes nothing.
  • A step that fails writes its message as one error annotation, which the run's summary shows, and exits with code 1; so does a first value that names no step, with the usage line of every step. Outside GitHub Actions, where GITHUB_ACTIONS isn't true, such as when a person builds on their machine, it writes the message as it is.
  • The build and test steps write their progress to standard output as they go, one line for each package they build or whose tests they compile, such as Building @noldova/example... Done., which ends with Failed. before the step's error.
  • The annotation goes to standard error, which GitHub Actions reads workflow commands from as it does standard output, so a step whose output the workflow keeps, such as the nightly version above, still shows it.
  • A fault, such as git failing to start, ends the run with its stack trace and exit code 1.

The tag step

pipelines tag <version> <commit> tags the released commit v<version> through GitHub's REST API, and never moves a tag. It reads GITHUB_API_URL and GITHUB_REPOSITORY, which GitHub Actions sets, and GITHUB_TOKEN, which the workflow passes in; the token needs to write the repository's contents, and is never written anywhere:

- env:
    GITHUB_TOKEN: ${{ github.token }}
  run: pipelines tag "$VERSION" "$COMMIT"

The job needs permissions: contents: write. GitHub refuses with 403 a tag at a commit whose workflow files differ from the default branch's, such as a released commit after which a workflow change merged, unless the token has the workflows permission, which a job's own token can't have; so tag the commit before anything that waits, such as a publish's approval, while it is still the default branch's latest. The step fails, naming the variable, when one is missing or empty, and with the request, the status and GitHub's message for an answer it doesn't expect, such as a missing permission; a 403 to the create also names such a commit as the likely cause when the token may write the contents.

The prune step

pipelines prune <version> <commit> <scope> <registry> <keep-versions> deletes each package's older release versions on GitHub Packages, https://npm.pkg.github.com/, keeping the newest <keep-versions> and every version a repository's lock file holds; for any other registry it fails and deletes nothing. A package @<owner>/<name> is the npm package <name> of the organization <owner>, so the scope is the organization's. It runs in a checkout of the commit, and reads GITHUB_API_URL and GITHUB_REPOSITORY, which GitHub Actions sets, and two tokens the workflow passes in, which are never written anywhere:

  • GITHUB_TOKEN deletes the packages' versions.
  • REPOSITORIES_TOKEN is a GitHub App installation's: the step reads every package-lock.json on the default branch of each repository the installation is given, archived ones included, except lock files under node_modules. Make it read-only, with contents and metadata read and nothing else, since the job that holds it deletes packages.
- id: app-token
  uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
  with:
    client-id: ${{ vars.APP_CLIENT_ID }}
    private-key: ${{ secrets.APP_KEY }}
    owner: ${{ github.repository_owner }}
    permission-contents: read
    permission-metadata: read
- env:
    GITHUB_TOKEN: ${{ github.token }}
    REPOSITORIES_TOKEN: ${{ steps.app-token.outputs.token }}
  run: pipelines prune "$VERSION" "$COMMIT" @noldova-com https://npm.pkg.github.com/ 5

The job needs permissions: packages: write, and runs in a release whose publish approval covers its deletes. The step reads lock files and deletes versions only from a private repository: before it reads any lock file, it reads the releasing repository with REPOSITORIES_TOKEN, and fails, reading no lock file and deleting nothing, when that repository is public or can't be read, since its lines name the repositories that lock a version and a public run's log anyone can read. So the App installation behind REPOSITORIES_TOKEN must reach the releasing repository too; one that doesn't makes the step fail the same way. The step lists the installation's repositories before it reads any lock file, and again after; when a list doesn't hold as many as GitHub counts, the two lists differ, GitHub lists only part of a repository's files, or a read fails, it deletes nothing. The step fails, naming the variable, when one is missing or empty, and with the request, the status and GitHub's message for an answer it doesn't expect, such as GitHub refusing to delete a package's last version. A 404 to a delete counts as a version already deleted only when GitHub's list no longer has it; otherwise the step fails.

The dependents step

pipelines dependents <version> <commit> proposes a release to the repositories that pin its packages, each in a pull request from the branch pipelines/update-<repository>, where <repository> is the releasing repository's name. It runs in a checkout of the released commit, and reads GITHUB_API_URL, GITHUB_SERVER_URL and GITHUB_REPOSITORY, which GitHub Actions sets, and GITHUB_TOKEN, which the workflow passes in:

- env:
    GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
    GIT_AUTHOR_NAME: example[bot]
    GIT_AUTHOR_EMAIL: 1+example[bot]@users.noreply.github.com
    GIT_COMMITTER_NAME: example[bot]
    GIT_COMMITTER_EMAIL: 1+example[bot]@users.noreply.github.com
  run: pipelines dependents "$VERSION" "$COMMIT"
  • The token is a GitHub App installation's: the repositories the installation is given are the ones the step checks, except the releasing repository and archived ones. From a public repository, whose run logs anyone can read, it checks only public repositories; it checks private ones only when GitHub answers that the releasing repository is private, so a failed read never widens the list; the step then prints a line saying so, naming only the releasing repository. It needs to write their contents, pull requests and issues, and is never written anywhere: git gets it through its environment, not its command line.
  • The workflow sets the commits' author and committer, such as the App's bot account, through git's environment.
  • npm refreshes each repository's lock files from the registries that repository names, without GITHUB_TOKEN; one that needs a token to read gets it from the workflow, as for an install.
  • The pins a released package needs as exact peers move with it, in the same pull request; a repository whose lock files hold a package that needs a moved package at another exact version, before or after the refresh, is left as it is, with a line that names that package.
  • The step prints each repository's line as soon as that repository is done, a failed one as an error, so a job stopped by its time limit still shows the repositories it finished; its last line is the summary.
  • A lock refresh that runs longer than 5 minutes is stopped and fails that repository, on Linux and macOS runners only.
  • The release notes are the section of the pull request whose merge commit is the commit, headed Release notes, or Release notes for <version> with the version, at any heading level, up to the next heading of that level or higher, or a line that starts with Agent:, a pull request's signature; without one, the proposal has none.
  • When the branch exists, the step replaces it, with --force-with-lease, only while it is at a commit of the step's own; then it updates the open pull request and its issue. Otherwise it opens an issue, which says what the new version is, and a pull request that closes it, against the repository's default branch.
  • A repository that has .github/workflows/relock.yml relocks itself: the step checks out every repository first and dispatches that workflow on each such repository's default branch, with the inputs commit, the checkout's head commit, and request, the release, so the runs go on together; then it finishes the repositories in order, reading each run every 15 seconds until it completes, downloading its artifact relock and reading relock.json from it, which the run's relock step wrote. All of a step's waits for runs share one budget of 20 minutes, so the job that runs the step needs a time limit of at least those 20 minutes plus the time its checkouts, relocks in its own checkouts, pushes and proposals take; with the dependents step's other work, 45 minutes is ample. A run that doesn't succeed, or isn't done when the budget is spent, a missing artifact or file, an archive the step can't read, a download GitHub refuses, and a relock of a commit other than the one the step checked out fail that repository. The token then also needs to write the repository's Actions, to dispatch, and to read them, for the run and its artifact; the artifact's download sends the token only to GitHub's API, never to the address it redirects to. A repository without the workflow is moved and relocked in the step's own checkout.
  • The step fails, naming the variable, when one is missing or empty; it fails for a repository, after trying every other, with git's exit code and error output, or with the request, the status and GitHub's message for an answer it doesn't expect.

The pins step

pipelines pins <version> <commit> proposes a shared repository's new tag v<version> to the repositories that call its workflows, each in a pull request from the branch pipelines/pins-<repository>, where <repository> is the shared repository's name. It runs in a clone of the shared repository that holds the commit, and reads the same variables as the dependents step, with a token from the same kind of App installation:

- env:
    GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
    GIT_AUTHOR_NAME: example[bot]
    GIT_AUTHOR_EMAIL: 1+example[bot]@users.noreply.github.com
    GIT_COMMITTER_NAME: example[bot]
    GIT_COMMITTER_EMAIL: 1+example[bot]@users.noreply.github.com
  run: pipelines pins "$VERSION" "$COMMIT"
  • A pin moves when it is written uses: <owner>/<repository>/<path>@<commit> # v<version>, with the calling repository's owner, and its version is older within the same major version, or it has no version and its commit is in the tag's history; a pin a major version behind, or with no version and a commit the tag doesn't hold, stays, and the proposal names it.
  • The checkout needs the shared repository's whole history, fetch-depth: 0, for the pins with no version.
  • The outside actions the shared repository's workflows pin at the commit, such as actions/checkout, move in the same pull request when a calling repository pins an older version; the proposal lists apart those that move to a new major version.
  • In a repository with a .github/dependabot.yml or .github/dependabot.yaml, Dependabot moves the outside actions, and the step moves only the shared repository's pins.
  • The token needs to write the repositories' workflows too, as well as their contents, pull requests and issues.
  • The output, the release notes, the branch and the failures work as in the dependents step.

When GitHub is briefly unavailable

The relock step

pipelines relock <repository> <request> <result file> [<lock file>=<npm script>...] runs in a dependent's relock.yml, which the dependents step dispatches, in a checkout of the commit the input commit names, after the job prepared it as the repository's own build does. It reads the registries with the job's own token, as the repository's install does, and needs no other; it writes the result file, which the job uploads as the artifact relock, holding relock.json:

- env:
    REQUEST: ${{ inputs.request }}
  run: pipelines relock "$GITHUB_REPOSITORY" "$REQUEST" "$RUNNER_TEMP/relock/relock.json" app/package-lock.json=lock:app

The prune, tag, dependents and pins steps send a request again, up to two more times, waiting 5 and then 15 seconds, when GitHub answers 502, 503 or 504, doesn't answer within a minute, or the connection fails. A failing answer with a Retry-After header of up to 60 seconds is sent again too, after that wait, such as a 403 for a rate limit. Any other answer comes back at once, such as a 403 or 404 without that header, or any answer with a longer Retry-After. The last answer, timeout or failed connection is what the step reports, naming the request. These retries count per request, and nothing bounds a step's requests together, so the job's timeout-minutes is the bound; since a request can be sent twice, a rerun is safe.

A create or delete that GitHub carried out but whose answer was lost is sent again, and is done, not a failure: the tag step finds the tag at the commit after GitHub refuses the second create, and the prune step reports the version as already deleted after a 404 and a new list without it.

From code

import { GitHubStepOutput, PipelinesProgram } from "@noldova/tools.pipelines.github";

const program = new PipelinesProgram(new GitHubStepOutput(process.stdout, process.stderr));
process.exitCode = await program.runAsync(["source", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"]);

The declaration file api/index.d.ts documents every member with its contract and examples.

License

MIT; see LICENSE.