watchdep
Sign inSource
Docs / Connect / 14

The Action and CI

Section
Connect
Page
14 of 16
Reading time
7 min
Read next
Agents (MCP)

Most of watchdep’s work happens in CI, where the code already is: sending the inventory, checking whether the code uses a flawed package, stopping a build, opening fix pull requests and reporting deployments. On GitHub, watchdep-action installs a pinned, checksummed copy of the command line and runs one command. Anywhere else, you call the command line yourself.

watchdep-action

- uses: actions/checkout@v4
- uses: kimathinjoki/watchdep-action@18cbad45072956cbc9c9442b8dffe9e315934499   # v1, pinned by commit SHA
  with:
    version: 0.1.0                                  # a release listed in the Action's checksums/
    command: gate
    args: --fail-on malicious,kev,severe

Pin the Action by a full commit SHA, never by a moving tag, so neither the Action nor the command line it installs can change under you. The current Action, v1, is commit 18cbad45072956cbc9c9442b8dffe9e315934499 and carries command line 0.1.0.

Inputs

Input Default What
command (required) scan, check, fix, gate or deployed
args (empty) More arguments for the command, for example --image app.tar or --sha ${{ github.sha }}
working-directory . The part’s folder
version (required) The command line release to use. It must be one the Action carries checksums for. There is no default and no “latest”: without it the step stops and names the versions the Action carries.
server (empty) Your watchdep server’s address, for scan, check, fix and deployed
token (empty) The part’s token (wdp_...), from a secret, for scan, check, fix and deployed
github-token ${{ github.token }} The repository’s own token, which fix opens pull requests with

Output

Output What
exit-code The command’s exit code. The step also fails with it.

The exit codes are the command line’s: 0 fine, 1 a finding meets the gate’s threshold, 2 incomplete (something could not be read or checked, or a source or the server did not answer), 3 a usage error.

The commands

Command Needs a server What it does
scan yes Sends the part’s inventory. Only the inventory leaves the runner.
check yes Checks whether the code uses each open finding’s package and sends draft verdicts (used, not used, unclear) with file paths and line numbers. A verdict never closes a finding. See The code check.
fix yes For each finding your workspace set to be fixed by pull request, upgrades the package with the project’s own package manager and opens one pull request per finding per part, or updates the open one. See Fixes.
gate no Checks against OSV, CISA KEV and EPSS directly and fails the build when a finding meets the threshold (default --fail-on malicious,kev).
deployed yes Reports a deployment, so production becomes the deployed commit.

Every flag of every command is in the command line reference.

How the Action verifies the command line

  1. It picks the one release file for the runner’s system (Linux, macOS or Windows) and architecture (amd64 or arm64).
  2. It looks up that file’s SHA-256 in checksums/<version>.txt, committed in the Action’s own repository. A version with no committed checksums stops the step.
  3. It downloads the file from the command line’s release into a fresh folder made for this run under $RUNNER_TEMP, and compares the SHA-256. A mismatch stops the step and deletes the download; nothing runs.
  4. Only then does it unpack watchdep, put it on the path and run the command.

There is no “latest”. Adding a version to the Action is a reviewed change to its repository, and pinning the Action by commit SHA pins the checksums with it. The checksums and the release address are fixed in the Action’s own files and never read from the job’s environment, so an earlier step writing to $GITHUB_ENV cannot swap the release or the checksums it is checked against.

Example workflows

Each example uses <commit-sha> where you put the Action’s full commit SHA (v1 is 18cbad4…, above), 0.1.0 for the command line release, https://watchdep.example.com where you put your watchdep server’s address, and a repository secret WATCHDEP_TOKEN holding the part’s token.

Scan and check on every push to production

Sends each push’s inventory, then the code check’s draft verdicts.

# .github/workflows/watchdep.yml
name: watchdep
on:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  watchdep:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kimathinjoki/watchdep-action@<commit-sha>
        with:
          version: 0.1.0
          command: scan
          server: https://watchdep.example.com
          token: ${{ secrets.WATCHDEP_TOKEN }}
      - uses: kimathinjoki/watchdep-action@<commit-sha>
        with:
          version: 0.1.0
          command: check
          server: https://watchdep.example.com
          token: ${{ secrets.WATCHDEP_TOKEN }}

Use the part’s production branch in branches. Inventories of other branches are stored and checked but raise no findings on the application.

The gate on pull requests

Stops a pull request’s build on a malicious release, an exploited-now finding in production scope, or anything severe. No server and no token are needed.

# .github/workflows/watchdep-gate.yml
name: watchdep gate
on: [pull_request]
permissions:
  contents: read
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kimathinjoki/watchdep-action@<commit-sha>
        with:
          version: 0.1.0
          command: gate
          args: --fail-on malicious,kev,severe

Daily fix pull requests

Opens, or updates, one pull request per finding the workspace wants fixed by pull request. fix needs write access to contents and pull requests, and the project’s package manager set up first, as your own CI does. The repository’s own token opens the pull requests; a person reviews and merges them. watchdep never merges, approves or turns on auto-merge.

# .github/workflows/watchdep-fix.yml
name: watchdep fix
on:
  schedule:
    - cron: "17 5 * * *"
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Set up the project's package manager first, as its own CI does.
      - uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
      - uses: kimathinjoki/watchdep-action@<commit-sha>
        with:
          version: 0.1.0
          command: fix
          server: https://watchdep.example.com
          token: ${{ secrets.WATCHDEP_TOKEN }}

The deploy step

In the deploy job, after the deployment succeeds: scan what was deployed (here the built image, saved as app.tar), then report the deployment. From then on, production is the last deployed commit, and a merged fix reads “fix merged, not yet in production” until the deployed commit’s inventory shows the fixed version.

      # ... after your image is built and saved (docker save -o app.tar ...) and deployed:
      - uses: kimathinjoki/watchdep-action@<commit-sha>
        with:
          version: 0.1.0
          command: scan
          args: --image app.tar
          server: https://watchdep.example.com
          token: ${{ secrets.WATCHDEP_TOKEN }}
      - uses: kimathinjoki/watchdep-action@<commit-sha>
        with:
          version: 0.1.0
          command: deployed
          args: --sha ${{ github.sha }}
          server: https://watchdep.example.com
          token: ${{ secrets.WATCHDEP_TOKEN }}

Run scan in the same job as deployed, so the deployed commit has an inventory. A deployed commit with no inventory is shown on the part in deep orange.

Other CI systems

The command line is one static binary and needs nothing else on the runner for scan, check, gate and deployed. Download a release in the job and check it against the release’s checksums (Linux amd64 here):

v=0.1.0
curl -fsSLO "https://github.com/kimathinjoki/watchdep-cli/releases/download/v$v/watchdep_${v}_linux_amd64.tar.gz"
curl -fsSLO "https://github.com/kimathinjoki/watchdep-cli/releases/download/v$v/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
mkdir -p bin && tar -xzf "watchdep_${v}_linux_amd64.tar.gz" -C bin watchdep
export PATH="$PWD/bin:$PATH"

Better still, copy checksums.txt into your own repository once and check against that copy, so a changed release cannot pass.

Then, with the server and the part’s token in the CI system’s secret variables:

export WATCHDEP_SERVER=https://watchdep.example.com
export WATCHDEP_TOKEN="$YOUR_SECRET_VARIABLE"
watchdep scan
watchdep check
watchdep gate --fail-on malicious,kev,severe

--server and --token work as well as the variables. To check the operating system packages production will actually run, read the built image: docker save -o app.tar <your image>, then watchdep gate --image app.tar or watchdep scan --image app.tar.

Things to know outside GitHub Actions:

  • deployed takes the commit from --sha, falling back to GITHUB_SHA, which only GitHub Actions sets. Elsewhere, pass it explicitly, for example watchdep deployed --sha "$CI_COMMIT_SHA" on GitLab.
  • fix opens pull requests on GitHub only. It needs GITHUB_TOKEN (contents and pull requests write) and GITHUB_REPOSITORY (owner/name), and GITHUB_API_URL for GitHub Enterprise. On other hosts, the fix is still named on every finding.
  • Exit codes are what the build should act on: 1 a finding meets the threshold, 2 incomplete, 3 a usage or watchdep.yml error (a path that does not exist or is not a folder included). A job that never checked the code out is not clean: gate finds no dependency files, says “Nothing was checked; this is not a clean result.” and exits 2. gate --allow-incomplete exits 0 instead of 2 when nothing meets the threshold, though its output still says the check did not look at everything.
  • --json switches all output, errors included, to JSON. Colour is used only on a terminal, and NO_COLOR turns it off.