Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
## What and why

<!-- What this pull request changes, and why. Name the issue: "Fixes #N". -->

## Behavior for callers

<!--
Answer with one word: yes or no. The check fails until you do.

"Behavior" means: defaults, the content of stdout and stderr, exit codes,
signals, which process runs the command, the meaning of the config, and
time limits. A change to an existing test under test/contract/ is
always "yes" (a new test is not).

For "yes":
- put "!" after the type or the scope of the title, such as
"feat(run)!: ...";
- add a section "## Updating from X" to docs/updating.md: who is
affected, what to do, and a command that shows the new way.

See docs/releasing.md, "Changes in behavior for callers".
-->

Changes behavior for existing callers: yes or no

## Tests

<!-- How you tested it, also the deny paths. -->
40 changes: 38 additions & 2 deletions .github/workflows/pr-title.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,16 @@ name: PR title
on:
# pull_request_target also runs for pull requests from forks. It runs with
# this repository's token, so this workflow must never check out or run
# code from the pull request. It only reads the title.
# code from the pull request. It reads only the title, the description,
# and the list of changed files. It checks out and runs code from the
# base branch (main) only.
# "edited" covers a new title and a new description.
pull_request_target:
types: [opened, edited, synchronize, reopened]

permissions:
pull-requests: read # read the pull request
contents: read # check out main, for the behavior-change gate
pull-requests: read # read the pull request and its changed files

concurrency:
# Check only the newest title of a pull request.
Expand Down Expand Up @@ -41,3 +45,35 @@ jobs:
refactor
build
style
# The behavior-change gate (docs/releasing.md, "Changes in behavior
# for callers"). It is in this job, so it is a required check too.
- name: Check out main, not the pull request
# Run the gate also when the title check failed, so the author
# sees both results at once.
if: ${{ !cancelled() }}
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# For pull_request_target, github.sha is the newest commit of the
# base branch. Never use a ref or a SHA of the pull request here.
ref: ${{ github.sha }}
persist-credentials: false
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
if: ${{ !cancelled() }}
with:
go-version-file: go.mod
# No cache in a pull_request_target run.
cache: false
- name: Behavior change for callers
if: ${{ !cancelled() }}
env:
TOKEN: ${{ github.token }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
set -euo pipefail
files="${RUNNER_TEMP}/changed-files.jsonl"
# Keep the names of all files, and the diff of docs/updating.md
# only. Only gh gets the token.
GH_TOKEN="$TOKEN" gh api --paginate "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files" \
--jq '.[] | {filename, previous_filename, status, patch: (if .filename == "docs/updating.md" then .patch else null end)}' > "$files"
unset TOKEN
go run ./tools/prgate --event "$GITHUB_EVENT_PATH" --files "$files"
6 changes: 6 additions & 0 deletions .golangci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,12 @@ linters:
linters:
- forbidigo
text: library code must not
# tools/ holds programs for CI, such as the behavior-change gate
# (tools/prgate). They are commands too, and may print.
- path: ^tools/
linters:
- forbidigo
text: library code must not
# os.ReadFile is forbidden only in library code under internal/. The
# config package has the file readers, and tests read their own files.
- path-except: ^internal/
Expand Down
14 changes: 13 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,10 @@ Planned. Each v1 issue adds its part.
- `docs/manual-ntfy-test.md` - the manual test with a real ntfy
server, on Android and on an iPhone (issue #24), with a table for
the results.
- `docs/releasing.md` - how releases are made and checked.
- `docs/releasing.md` - how releases are made and checked, and the
behavior-change gate.
- `docs/updating.md` - one section per change in behavior for callers
("## Updating from X"): who is affected, what to do, a command.
- `docs/agent-browser.md` - website logins with agent-browser: the
plugin entry, the login steps and the `agents` Chrome profile.
- `docs_test.go` (at the root of the module) checks that no shell
Expand All @@ -87,6 +90,9 @@ Planned. Each v1 issue adds its part.
- `test/e2e/` - the end-to-end test with `sshd` in a container (DESIGN.md
section 17). Build tag `e2e`. The image of the container is
`test/e2e/testdata/sshd`.
- `tools/prgate/` - the behavior-change gate that the PR title workflow
runs from `main` (docs/releasing.md, "Changes in behavior for
callers"). `.github/pull_request_template.md` has its line.
- `.claude/agents/security-reviewer.md` - the security review every change
gets.

Expand Down Expand Up @@ -138,6 +144,12 @@ that it makes.
titles follow [Conventional Commits](https://www.conventionalcommits.org/)
(`feat:`, `fix:`, `docs:`, `test:`, `ci:`, `chore:`). Pull requests are
squash merged. Never push to `main` directly.
- **Every pull request description** has the line
`Changes behavior for existing callers: yes` or `no`. For `yes`, the
title has `!` (`feat(run)!: ...`) and the pull request adds a section
`## Updating from X` to `docs/updating.md`. A change to an existing
file under `test/contract/` (not a new test, not its README) is
always `yes`. CI checks it (docs/releasing.md).
- **Open work is a GitHub issue** with a "Done when" checklist, never a TODO
file.
- **Every error says how to fix it.** Every error that a person or an
Expand Down
11 changes: 11 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4578,6 +4578,17 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`):
- GitHub Actions are pinned to a commit SHA.
- Pull request titles follow Conventional Commits. Pull requests are squash
merged.
- Every pull request says if it changes behavior for existing callers
(defaults, stdout and stderr, exit codes, signals, which process runs
the command, config meaning, time limits). For `yes`, the title has `!`,
so release-please lists it under "⚠ BREAKING CHANGES", and the pull
request adds a section to `docs/updating.md`. A change to an existing
file under `test/contract/` (not a new test, not its README) is
always `yes`. `tools/prgate` checks this in the PR
title workflow, run from `main` with `pull_request_target`; it reads
only the title, the description, the author, the branch name and the
changed files (names, status, and the added lines of `docs/updating.md`), and
never runs code of the pull request. See docs/releasing.md.
- Pull request titles may use the type `security` (also `security(deps)`)
for a real security fix. It puts a `### Security` section first in
CHANGELOG.md and in the release notes; a line may name advisory IDs
Expand Down
93 changes: 92 additions & 1 deletion docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,95 @@ For a breaking change, add `!` after the type. For example:
The **PR title** check tests the title. If the check fails, edit the title.
The check runs again by itself.

## Changes in behavior for callers

Before 1.0, a feature and a breaking change both make a minor release
(see [Versions before 1.0](#versions-before-10)). So the version number
does not warn the people who update. 0.6.0 changed a default that
programs and scripts depend on (#171), and it was listed as a normal
feature (#191). This gate makes such a change visible.

### The line in the description

The description of every pull request has this line, with `yes` or `no`
([`.github/pull_request_template.md`](../.github/pull_request_template.md)):

```text
Changes behavior for existing callers: no
```

"Behavior" means: defaults, the content of stdout and stderr, exit codes,
signals, which process runs the command, the meaning of the config, and
time limits. A program or a script that uses nodkey can break when one
of them changes.

For `yes`, the pull request must also:

- have `!` after the type or the scope of the title, for example
`feat(run)!: mask the output by default`;
- add a section `## Updating from X` to
[docs/updating.md](updating.md). It says who is affected, what to do,
and gives a command that shows the new way. `X` is the newest release
that still has the old behavior, for example `0.5.0 or older`.

### The check

The **PR title** workflow runs the check in its job
**Conventional Commits title**, after the title check. This job is
already a required check of `main`. The check fails when:

- the line is missing, is there more than once, or has another value
than `yes` or `no` (in small letters, with nothing else; a line in an
HTML comment `<!-- -->` does not count);
- the answer is `yes` and the title has no `!`;
- the answer is `yes` and the pull request adds no line
`## Updating from X` to `docs/updating.md`;
- the answer is `no` and the title has a `!`;
- the pull request changes, removes or moves a file under
`test/contract/`, and the answer is `no`. These tests pin what callers
see, so a change to one of them is a change in behavior for callers.
A new test file right in `test/contract/` (a name that ends in
`_test.go`) does not count: a new test pins behavior that callers
already have. A change to `test/contract/README.md` does not count
either. Any other new file there counts, such as a `go.mod` or a file
in `testdata/`, because it can change the tests that are there. A
new test file can still change the others, for example with a
`TestMain`: the review must check this.

The error says what to fix. Edit the title or the description: the
check runs again by itself.

Two kinds of pull requests need no line:

- the release pull request of release-please: its author is the release
App, its branch is `release-please--branches--main`, and it changes
only `CHANGELOG.md` and `.release-please-manifest.json`. Its commits
passed the check one by one;
- a pull request of Dependabot with no `!` in the title that changes
only `go.mod`, `go.sum`, files under `.github/workflows/` and files
under `test/e2e/testdata/sshd/`.

The check is `tools/prgate`, with its tests in
`tools/prgate/main_test.go`. The workflow runs it with
`pull_request_target`, from the code on `main`, never from the pull
request. It reads only the title, the description, the author and the
branch name of the pull request, and the list of changed files from the
GitHub API: their names, their status (added, changed, removed, moved),
and the diff of `docs/updating.md` only, as text. It never prints text of the pull request to the log. A change to
the check itself takes effect only after it is merged.

### "⚠ BREAKING CHANGES" in the release notes

release-please lists a commit with `!` after the type or the scope under
**⚠ BREAKING CHANGES**, at the top of the release notes and of
CHANGELOG.md. The commit on `main` must keep the `!`. It does: the
squash commit takes the pull request title as its message (repository
setting: the default commit message of a squash merge is the pull
request title; checked on 2026-11-17). So never change the title in the
merge dialog, and never remove the `!` from it. Before you merge a
release pull request, check that each change of `docs/updating.md` since
the last release has its line under **⚠ BREAKING CHANGES**.

## Security fixes

Use the type `security` for a pull request that fixes a real security
Expand Down Expand Up @@ -173,7 +262,9 @@ without activity. If this happens, turn on the CI workflow again in the
These settings protect `main` and the releases:

- **Ruleset for `main`**: changes only through a pull request; the CI checks
and the PR title check must pass; no force push; `main` cannot be deleted.
and the PR title check (with the gate of
[Changes in behavior for callers](#changes-in-behavior-for-callers))
must pass; no force push; `main` cannot be deleted.
- **Rulesets for `v*` tags**: nobody can move or delete a tag, not even the
release App. Only the release App can create one.
- **Immutable releases**: on.
Expand Down
5 changes: 5 additions & 0 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -2749,6 +2749,11 @@ such as a password command, and each script that checks its parent.
[Section 11, "Keep the mask on"](#keep-the-mask-on-password-commands-and-wrappers)
shows how to change them, with the mask still on.

**Changes in behavior.** [docs/updating.md](updating.md) lists each
change that can break a program or a script that uses nodkey, with what
to do. Read its sections from your version up to the new one before you
update.

### New versions of bws and bw

Install them in the same way as the first time
Expand Down
66 changes: 66 additions & 0 deletions docs/updating.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Updating nodkey

This page lists each change in nodkey that can break a program or a
script that uses it: a new default, other output on stdout or stderr, a
new exit code, other signals, another process that runs the command, a
new meaning of a config key, or a new time limit. Before you update,
read every section from your version up to the new one.

Each section says who is affected, what to do, and gives a command that
shows the new way. The steps of an update itself are in
[docs/setup.md, section 13](setup.md#13-upgrades-and-key-changes).

From 2026-11-17 on, the release notes list such a change under
"⚠ BREAKING CHANGES", and its pull request adds a section here
([docs/releasing.md](releasing.md#changes-in-behavior-for-callers)).
Older releases listed it as a normal feature.

## Updating from 0.5.0 or older

**What changed (0.6.0, #171).** `nodkey run` masks the values that it
fetched: it replaces each one with `***` in the command's stdout and
stderr. This is now the default whenever stdout or stderr of
`nodkey run` is not a terminal. A masked `nodkey run` stays as the parent
of the command: it does not replace itself with the command, as 0.5.0
did. On a terminal (stdout and stderr both a terminal), nothing changed.

**Who is affected.**

- A program that reads the output of `nodkey run` through a pipe, such
as a mail client with a password command like
`nodkey run --secret P=mail-read -- printenv P`. It now gets `***`, and
its login fails.
- A script that checks that its parent is the process that started
`nodkey run`. Its parent is now a process named `nodkey`.

**What to do.** Keep the mask on. With `--no-mask`, even a plain
`printenv` or a debug line of the command shows the value.

- For a password command: run the program itself inside `nodkey run`,
and let its password command read the value from the program's own
environment. For example, with `password.cmd = "printenv MAIL_READ"` in
the program's config:

```sh
nodkey run --secret MAIL_READ=mail-read --reason "read the mail" -- mail-client sync
```

- For a parent check: accept a parent named `nodkey`, and look at that
process's parent. nodkey is not dumpable, so read `/proc/PID/stat`, not
`/proc/PID/exe`:

```sh
parent=$PPID
name=$(sed 's/^[0-9]* (\(.*\)) .*/\1/' "/proc/$parent/stat")
if [ "$name" = nodkey ]; then
parent=$(awk '{print $4}' "/proc/$parent/stat")
fi
```

A process name is not proof: any program of the same user can take
the name `nodkey`. Use this only where the parent check is a
convenience, not a security boundary.

The full text, with what a masked command gets (stdin, file descriptors)
and the risks of each way, is in
[docs/setup.md, "Keep the mask on"](setup.md#keep-the-mask-on-password-commands-and-wrappers).
Loading
Loading