blackoutsecure/Blackout Secure Upstream Watcher

Detect upstream version changes from GitHub Releases, branch HEAD, tags, npm, PyPI, container registries, or any URL.

View on GitHub

Trust Signals

Scorecard Score: not yet scored
Maintenance Recency: Activelast commit Jun 8, 2026
License: Apache 2.0

Pinned Snippet

workflow.ymlSHA-pinned

uses: blackoutsecure/bos-upstream-watcher@44cac53ae99ca777035398a8764449f708986bef # v1.1.1

tags can be moved; commit SHAs can't. why a SHA?

Inputs

name	description	required	default
source	Provider. One of: github_release — repos/{repo}/releases/latest github_branch_file — raw file from a branch HEAD github_tags — repos/{repo}/tags, pick highest SemVer container_image — container registry tags, pick highest SemVer (supports docker.io, ghcr.io, quay.io) npm — registry.npmjs.org/{pkg}/latest pypi — pypi.org/pypi/{pkg}/json generic_url — fetch URL, apply version_regex	yes	—
upstream_repo	`owner/name` of the upstream GitHub repo. Required for `github_release`, `github_branch_file`, and `github_tags`.	no	""
upstream_branch	Branch name. Required for `github_branch_file`; ignored for `github_tags` (tags are repo-wide).	no	""
version_file_path	Repo-relative path inside `upstream_branch` whose raw contents are the version string. Used only for `github_branch_file`. Pair with `version_regex` to extract the version from a structured file (for example a Debian `debian/changelog`).	no	version
image_ref	Container image reference. Used only for `container_image`. Supported registries: * `docker.io/<namespace>/<image>` (or bare `<namespace>/<image>`, or bare `<image>` for official `library/` images) `ghcr.io/<owner>/<image>` — public images only in this revision * `quay.io/<namespace>/<image>` — public repos only in this revision Other registries (gcr.io, mcr.microsoft.com, ECR, ACR) are rejected with an explicit error; PRs adding them are welcome.	no	""
package_name	Package name. Required for `npm` and `pypi`. npm scoped names (`@scope/name`) are supported.	no	""
version_url	URL to fetch. Required for `generic_url`.	no	""
version_regex	Python regex applied to the fetched body. The first capture group is the version. Required for `generic_url`; optional for `github_branch_file` (when unset, the trimmed file body is the version). Short SemVer (`X`, `X.Y`) is padded to `X.Y.Z`.	no	""
tag_pattern	Optional Python regex used to filter candidate tags/versions for `github_tags`, `container_image`, and `github_release` (when `include_prereleases: true`) before SemVer ranking. Default `^v?\d+\.\d+\.\d+([-+][0-9A-Za-z.-]+)?$`.	no	""
include_prereleases	For `source: github_release` only. When `'true'`, the action lists `repos/{repo}/releases` (which includes pre-releases) instead of `releases/latest`, filters by `tag_pattern`, and picks the highest SemVer. Required for upstreams that ship only pre-releases (e.g. `actions/runner`, betas, nightlies). Default `'false'` preserves the v1.0 behavior. Ignored for all other providers.	no	false
strip_v_prefix	Strip a leading `v` from the resolved version.	no	true
tracker_path	Repo-relative path to the tracker JSON file. Created on first run; rewritten when the upstream version changes. Empty disables the file (the action then always reports `changed=true`).	no	.github/upstream/tracked-release.json
github_token	Token used for authenticated GitHub REST calls. Falls back to `github.token`. Anonymous calls are rate-limited to 60/hr.	no	${{ github.token }}
user_agent	Custom `User-Agent` header sent on outbound HTTP requests. Defaults to `bos-upstream-watcher/<version>`.	no	""

Outputs

name	description
changed	`true` when the upstream version differs from the tracker file.
version	Resolved upstream version (with `v` stripped when `strip_v_prefix` is true).
tag	Raw upstream tag name (preserves any leading `v`).
commit	Upstream commit SHA. Empty for sources that do not map to a commit (`npm`, `pypi`, `container_image`, `generic_url`).
source_url	URL that was consulted, for traceability.
tracker_path	Repo-relative path of the tracker file (echoes the input).
label	Canonical identifier for the upstream: `owner/name` for GitHub sources, the package name for `npm`/`pypi`, the canonical `<registry>/<ns>/<image>` for `container_image`, or the URL for `generic_url`. Use in commit messages / Slack notifications instead of an `inputs.* \|\| inputs.*` fallback chain.
release_url	HTML URL of the GitHub Release. Populated for `source: github_release` only; empty for other providers.
release_name	Display name of the GitHub Release (may differ from the tag). Populated for `source: github_release` only.
release_body	Markdown release notes from GitHub Releases. Multi-line value (emitted via heredoc to GITHUB_OUTPUT). Populated for `source: github_release` only.
published_at	ISO 8601 publication timestamp of the GitHub Release (e.g. `2024-09-12T18:23:00Z`). Populated for `source: github_release` only.