Dependency updates as one static Go binary: it reads your existing Renovate configuration, plans every change before it writes one, and opens merge requests that say what they bring. The datasources and managers are platform-neutral; the platform behind them - where the merge requests, the dashboard issue and the project listing live - is an interface with two implementations: GitLab, proven in production across an estate of two hundred repositories, and GitHub, in production since September 2026 on a first repository (a Helm chart, run as a GitHub App, without automerge) and proven against a fake that speaks the API for the rest.
config → resolve → checkout → discover → extract → lookup → classify → plan → apply → publish
Every run produces a machine-readable plan before the first byte is
written — pinup whatif stops there, pinup run continues. A plan explains
absence: every update that is held carries its reason, when the hold lifts
and which rule imposed it.
An hourly Renovate run across two hundred repositories took 40 minutes of
wall time and 128 runner minutes, on a Node runtime with a sidecar for every
datasource it did not speak. pinup replaces that runner for the same
repositories and the same configuration in 10.6 minutes of wall time and 75
runner minutes, with no runtime and two third-party dependencies, and without
moving a line of anyone's renovate.json:
- Renovate-compatible configuration.
extends, presets,packageRules(concatenated, applied in order), custom regex managers with Handlebars templates, JSONata transforms, schedules,minimumReleaseAge,internalChecksFilter, lock-file maintenance,postUpgradeTasks, vulnerability alerts (OSV), the dependency dashboard with its checkboxes.pinup migratereports, key by key, what a configuration uses and what pinup supports. - An effective label beside the declared one. A rule with
analyze: trueasks an analyzer what actually changed: for a Helm chart, the application's own version, the values keys the new chart no longer has (breaking-values), the subcharts, and the container images the chart places out of its own values - which are in no file of the consumer's repository, so nothing else updates or pins them.matchEffectiverules read the label, the merge request shows the evidence, and the stricter of the two labels decides automerge unless a rule saystrustEffective: true- for the chart vendor that raises the major on every release.
- A released tag that moved is not an update. A digest that no longer
matches the tag a file pinned means the tag was re-pushed. For
latestthat is the tag doing its job; forv2.10.0it is a published version rewritten under a pin that named it, and the plan says which of the two it saw. - Renovate-compatible branches. The same branch names and titles, so an estate switches without a single duplicated merge request; open branches are adopted.
- A shadow mode.
pinup shadowcompares pinup's plans with the merge requests Renovate has open, run after run, and refuses to call itself right until the two agree — with a control repository that must differ. - Clean room. Renovate is AGPL-3.0; pinup is Apache-2.0. Nothing was copied. Behaviour was observed by executing the pinned Renovate container and re-implemented from recorded input/output pairs, which are the test suite.
go install github.com/ohartwig/pinup/cmd/pinup@latestStatic binaries for Linux and macOS (amd64, arm64) come with every
release, with SHA256SUMS and
a detached cosign signature over it. They are built and signed once, in the
author's pipeline, and the same files are published on GitHub — nothing is
rebuilt there.
cosign verify-blob --key cosign.pub --signature SHA256SUMS.sig \
--insecure-ignore-tlog=true SHA256SUMS
sha256sum -c SHA256SUMScosign.pub is the public half of the signing key, which
lives in AWS KMS; the same key signs the container images.
Or as a container image — ghcr.io/ohartwig/pinup
(git, gpg, nothing else) and
ghcr.io/ohartwig/pinup-toolchain
(plus composer, npm, node, go, yarn and pnpm for lock refreshes),
linux/amd64 and linux/arm64, signed with the same key:
cosign verify --key cosign.pub --insecure-ignore-tlog=true ghcr.io/ohartwig/pinup:0
docker run --rm -v "$PWD:/workspace" ghcr.io/ohartwig/pinup:0 \
pinup whatif --repo . --config .pinup.yaml --report plan.jsonThe image carries the released binary, checked against SHA256SUMS, and it
is the image the author's own pipeline runs, copied by digest with its
signature: nothing is compiled or built a second time on GitHub.
Container images has the tags, the verification
and what each one is for.
Four steps, each complete on its own. Stop where you have what you need.
whatif resolves the configuration, reads the manifests, looks the
versions up and writes a plan. It changes nothing and needs no token
(private registries aside). Any repository with a configuration will do -
pinup's own .pinup.yaml or a renovate.json that is already there; with
neither, a .pinup.yaml holding extends: [config:recommended] is enough
to start.
cd a-repository
pinup whatif --repo . --config .pinup.yaml --report plan.json
# what would move, and what is held back and why
jq -r '.updates[] | "\(.dep.depName) \(.dep.currentValue) -> \(.newValue) \(.blocks[0].reason // "ready") \(.blocks[0].origin | if . then "\(.source)[\(.rule)]" else "" end)"' plan.jsonA line like lodash 4.17.20 -> 4.17.21 ready becomes a branch on the
next run; redis 20.13.4 -> 28.1.0 dependencyDashboardApproval packageRules[3] says which rule holds the major and where it lives
(config[-1] is the top level of the configuration).
--now 2026-01-01T00:00:00Z plans as of another moment - the way to check
a schedule or a minimumReleaseAge without waiting for it.
run does what whatif does and then pushes the branches, opens or
updates the merge requests and keeps the dashboard issue. It needs the
platform and a token that may write to the project.
export PINUP_GITLAB_URL=https://gitlab.example.org
export PINUP_GITLAB_TOKEN=glpat-… # scopes: api, write_repository
export PINUP_GIT_NAME="Dependency Bot" PINUP_GIT_EMAIL=bot@example.org
export PINUP_SIGNING_FORMAT=none # or openpgp / ssh + PINUP_SIGNING_KEY
pinup run --project group/project --config .pinup.yaml --report plan.jsonOn GitHub the same command reads PINUP_GITHUB_TOKEN and
--project owner/repository; a GitHub token with no GitLab instance in
the environment selects the platform. --dry-run stops after the plan
with the platform's view of the open merge requests folded in - the
safe first run against a real project.
What you get: one branch per update or group, named the way Renovate
names it (renovate/lodash-4.x), a merge request whose description lists
the edits and the release notes, automerge set where a rule says so, and
a "Dependency Dashboard" issue that lists every held update with a
checkbox to approve it. A ticked box is an instruction to the next run,
and it is honoured from whoever may edit the issue - Reporter and above
on the project. The dashboard is the operators' surface by design; a
project where Reporter is handed out widely should know that an approval
there is one of them.
Put the estate's rules in a runner project and let each repository extend it. Nothing else has to change in the repositories, and a repository with no file at all still gets the runner's defaults.
# any repository: .pinup.yaml
extends: ["local>group/pinup-runner"]pinup run --autodiscover '["group/**", "!group/archive/**"]' \
--config 'local>group/pinup-runner' --report 'reports/%s.json'--autodiscover runs every non-archived project the token can see that
matches the globs, eight at a time; %s becomes the project path.
docs/examples/default.json is a
complete runner configuration - automerge for patch and minor, dashboard
approval for majors, an analyzer rule for a chart vendor that raises the
major on every release.
docs/examples/gitlab-ci.yml is a
scheduled GitLab job: a toolchain image with pinup, composer, npm and go
on the PATH, the token as a masked variable, the lookup cache kept
between runs, the plans as artefacts.
docs/examples/github-actions.yml
is the same on GitHub Actions. Hourly is fine: a run over two hundred
repositories takes ten minutes of wall time, and a run that finds nothing
new writes nothing.
- Keep the configuration.
pinup migrate --config renovate.jsonclassifies every key as supported, partial or unsupported, with the difference spelled out (configuration). Nothing in the repositories changes;pinup migrate --to yamlrewrites a file as.pinup.yamlif you want it to, and only then.pinup advisethen says what the file could do better - anignorePathsthat dropped the preset's list, an automerge over majors, a preset extended twice - and--fixapplies it, byte for byte, behind a check that the resolution changed only where the fixes said. - Keep the branches. The same branch names and titles, so an open Renovate merge request is adopted, not duplicated. A branch somebody else committed to is left alone.
- Run both for a while.
pinup shadow --plans 'reports/*.json'compares pinup's plans with what Renovate has open and fails when a difference persists across two runs without a triaged reason - with a control repository that must differ, so the comparison is proven able to fail before its first verdict is believed. - What is not there: Bitbucket and Azure DevOps; managers pinup does not read (Maven, Gradle, NuGet, Cargo, pip requirements); Mend Merge Confidence - pinup classifies itself (effective classification) and calls no third party.
pinup whatif --repo . --config .pinup.yaml --report plan.json # plan, write nothing
pinup run --project group/project --config … --report plan.json # plan, apply, publish
pinup run --autodiscover '["group/**"]' --config … --report 'reports/%s.json'
pinup run --released group/library@1.4.0 --config … # the fast lane: only that dependency's consumers
pinup print-config --config .pinup.yaml --explain # what a configuration resolves to, and which rule set each value
pinup migrate --config renovate.json [--to yaml] # which keys pinup supports; a YAML rewrite
pinup advise --config .pinup.yaml [--plan plan.json] [--fix] # what to change - performance, security, hygiene - and why
pinup advisories --index '.pinup/consumers.json' # OSV over everything the runs have seen, no clone
pinup arm-watch --filter '["group/**"]' # arm automerge once GitLab has the pipeline, no clone
pinup shadow --plans 'reports/*.json' # compare with the merge requests another tool has openpinup <command> -h prints every flag. The documentation - getting
started, every command, the configuration keys, the plan format,
platforms, tasks, security - is in docs/ and, as web
pages, at https://ole-hartwig.eu/en/open-source/pinup (German:
https://ole-hartwig.eu/open-source/pinup).
pinup reads one of .pinup.yaml, .pinup.yml, .pinup.json,
.pinup.jsonc, renovate.json, renovate.json5, .renovaterc and
.renovaterc.json in the repository - exactly one: two of them is an error,
not a silent choice - resolved over the configuration the run was
started with (--config), which may itself be a local> preset fetched
from the instance. The vocabulary is Renovate's; the merge semantics are
Renovate's (objects deep-merge, arrays replace, packageRules concatenate,
null clears). Every resolved value keeps its origin chain, and
print-config --explain shows it.
Environment:
| Variable | Meaning |
|---|---|
PINUP_PLATFORM |
gitlab (the default) or github; a GitHub token with no GitLab instance in the environment means github |
PINUP_GITLAB_URL / CI_SERVER_URL |
the GitLab instance |
PINUP_GITLAB_TOKEN / GITLAB_TOKEN |
a personal access token (api, write_repository); CI_JOB_TOKEN is used when none is set (read-only) |
PINUP_GITHUB_URL / GITHUB_SERVER_URL |
the GitHub host; github.com when unset |
PINUP_GITHUB_TOKEN / GITHUB_TOKEN |
a token with repo (pull requests, issues, contents) - a fine-grained one with contents, pull requests and issues read/write; on github.com it serves the github-* datasources as well |
PINUP_REGISTRY_HOST / CI_REGISTRY |
the estate's container registry; the token is exchanged for a pull token there and nowhere else |
GITHUB_COM_TOKEN |
for GitHub lookups and release notes, bound to api.github.com |
PINUP_GIT_NAME, PINUP_GIT_EMAIL, PINUP_SIGNING_FORMAT, PINUP_SIGNING_KEY |
who commits and how commits are signed (openpgp or ssh); unsigned only with the explicit word none |
PINUP_CACHE |
the lookup cache (bbolt); release lists, first-seen records, advisories, release notes |
PINUP_ALLOWED_COMMANDS |
JSON array of anchored patterns a postUpgradeTasks command must match — the runner's decision, never a repository's |
PINUP_PLUGIN_ENV |
variables a task may see besides PATH, LANG, TZ; tokens and keys never cross |
PINUP_TASK_NETRC |
a .netrc written into each task's scratch HOME (machine <host> login <user> password <read-only token>), for a toolchain that fetches first-party modules over https - go mod tidy on a private Go module; never handed over as a variable |
PINUP_RUNNER_PROJECT |
the project repositories extend the runner configuration from, as local><project>; taken from --config local>… when that names it |
PINUP_APK_VIEWS |
apk indexes served natively besides the public Wolfi repository: {"custom.<name>": {"mirrors": [...], "arches": [...]}}; a configuration's customDatasources entry of the same name is superseded |
- The platform token is sent only to the API paths pinup itself calls, never to a URL a repository configuration names; it is dropped on any redirect off its host.
- Tasks (
postUpgradeTasks, lock refreshes) run as argv without a shell, against an allowlist on the compiled command, with an allowlisted environment and a scratchHOME; their result is validated against the file scope they were given. - Text from elsewhere — release notes,
prBodyNotes— is sanitised before it reaches a merge request: no quick actions, no stray mentions. - The lookups' HTTP client contacts no third-party service beyond the
registries a dependency names and OSV when
osvVulnerabilityAlertsis on.
Report vulnerabilities as SECURITY.md says.
Go 1.27, git; gpg and ssh-keygen for the signing tests. No other
tooling.
go build ./cmd/pinup
go test ./...
go vet ./... && gofmt -l .Six layers, enforced by a test rather than a convention; hermetic HTTP through servers that speak the protocol, with a transport that fails a test on any unregistered host; golden repositories that are versioned by directory, never rewritten; a mutation suite that breaks each harness layer on purpose and must see it go red. CONTRIBUTING.md has the rules. The architecture notes, the specification with its measured corrections and the task list live with the development repository, not in this mirror; ask if you need them.
The canonical public home is https://github.com/ohartwig/pinup; that is the module path and where tags and releases appear. Development and the release pipeline run on the author's GitLab, which mirrors here — issues and pull requests here are read.
Apache-2.0 — see LICENSE; releases up to 0.33.0 were MIT. Renovate, whose behaviour pinup reproduces, is AGPL-3.0 and none of it is included here; see NOTICE.