Skip to content

docs: releasing.md must stand alone, without links to nodkey's docs #6

Closed

Description

@groupsky

docs/releasing.md points to nodkey three times:

  • line 4: "the same release setup as nodkey";
  • line 50: "the release GitHub App (the one nodkey uses)";
  • line 52: the App setup steps are only a link to nodkey's docs/releasing.md.

pullgate is its own project. A reader (or a fork) must be able to set up releases from pullgate's docs alone. If nodkey's docs change or move, these links break or say something else.

Write the steps in pullgate's own docs instead. The section "One-time setup" must cover, in plain words:

  • why a GitHub App and not GITHUB_TOKEN (a GITHUB_TOKEN push or PR does not start workflows, so the release PR could not pass the required checks) and not a personal token;
  • creating the App, or reusing the organization's existing release App: no webhook, repository permissions Contents: Read and write and Pull requests: Read and write, nothing else, installable only on this account;
  • installing it on this repository only (Only select repositories);
  • a new private key for this repository, and how to compute its fingerprint (openssl rsa -in key.pem -pubout -outform DER | openssl sha256 -binary | openssl base64 -A) and compare it with the Key pairs page;
  • that the keys do not keep repositories apart: any key of the App can get a token for every repository the App is installed on;
  • the gh variable set / gh secret set commands (already there), secret first, then delete the .pem file;
  • the repository settings (already there).

Use generic names (<organization>, <organization>-release), no organization-specific App name.

Done when

  • git grep -ni nodkey finds nothing in docs/releasing.md.
  • git grep -ni nodkey in the whole repo finds nothing that sends the reader to nodkey's docs for a step (a short "inspired by" note elsewhere is fine).
  • The "One-time setup" section covers every point above, and a reader can follow it without opening another repository.
  • The PR title is docs: ….

Activity

  1. groupsky commented on Nov 12, 2026

    @groupsky
    ContributorAuthor

    Done in #12 (8cc4e3a, title docs: …).

    • git grep -ni nodkey on main finds nothing in the whole repo.
    • "One-time setup" now covers: why an App (not GITHUB_TOKEN, not a personal token); creating or reusing the App (no webhook, Contents and Pull requests Read and write, nothing else, only on this account); installing it on this repository only; a new key per repository and its fingerprint with openssl, compared with the Key pairs page; that keys do not keep repositories apart; the environment limited to main, then the secret, then the variables, then delete the .pem; the repository settings. Names are generic (<organization>, <organization>-release).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority: lowDo when nothing else waits

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions