Installing On-Premises Tools with Scoop

Zeugwerk's on-premises tools (zkmake, zkdoc, zkinstall) are distributed via a private Scoop bucket. Scoop is a Windows package manager that handles installation, versioning, authentication, and updates automatically. Once a node is configured, tools are available in any pipeline script and stay current without manual steps.

Note

This page covers installation for self-hosted Windows CI/CD nodes (Jenkins, GitLab Runner, Azure DevOps agent, etc.). If you are using hosted runners, use zkbuild on GitHub Actions, zkbuild on Bitbucket Pipelines, or zkdoc-action instead.

Prerequisites

Requirement	Notes
Windows	Scoop and the on-premises tools run on Windows only.
PowerShell 5.1 or later	Included with Windows 10 / Server 2016 and later.
Zeugwerk token	Provided during onboarding. Contact us if you don't have one yet.
Internet access to `api.zeugwerk.dev` and `github.com`	Required for the initial install and for updates.

One-time node setup

Rather than running this manually on each node, the recommended approach is a housekeeping pipeline: a dedicated CI/CD job that runs automatically whenever a new agent comes online and on a nightly schedule on existing nodes. It ensures every node is always in the correct state without any manual steps.

How to implement this depends on your CI/CD system. In Jenkins, this is typically a parameterized pipeline job triggered on agent registration and scheduled via a cron expression. In GitLab, you can use a scheduled pipeline with a shell runner tag. The job runs the bootstrap below. It is safe to run repeatedly: an existing Scoop install and an existing bucket are left in place, and the token entry is written again.

The script installs Scoop when it is missing, registers your token so downloads from api.zeugwerk.dev send an Authorization header, and adds the Zeugwerk bucket. If git is missing it installs that too, because Scoop clones buckets with git. Install the Zeugwerk tools you need afterwards. Store the token as a secret in your CI/CD credential store (a Jenkins credential, a GitLab CI/CD variable, etc.) and inject it as ZEUGWERK_TOKEN.

$env:ZEUGWERK_TOKEN = '<your token>'
irm https://zeugwerk.dev/scoop/bootstrap.ps1 | iex

Some CI agents run PowerShell elevated. Scoop's installer refuses that unless you allow it:

$env:ZEUGWERK_TOKEN = '<your token>'
$env:ZEUGWERK_SCOOP_RUNASADMIN = '1'
irm https://zeugwerk.dev/scoop/bootstrap.ps1 | iex

Then install the tools this machine needs:

scoop install zkmake zkdoc zkinstall

Using tools in a pipeline

Once the node is set up, tools are on the PATH and can be called directly in any pipeline script. A minimal GitLab CI example:

build:
  tags: [windows]
  script:
    - scoop update zkmake zkdoc
    - zkmake build --update-snapshots --kill-all
    - zkdoc --docfx reference --output documentation .
  artifacts:
    paths: ["*.library", "documentation/"]

Scoop resolves the current version, handles authentication against the download API transparently, and serves from the local cache if the binary has not changed since the last run.

Updating tools

To update all installed Scoop packages to their latest versions:

scoop update *

To update only specific tools:

scoop update zkmake zkdoc

Pinning a specific version

If a pipeline requires a fixed tool version:

scoop install zkmake@1.9.0
scoop hold zkmake        # prevents scoop update from upgrading it

To unpin and allow updates again:

scoop unhold zkmake

Uninstalling

scoop uninstall zkmake

To also remove the Zeugwerk bucket:

scoop bucket rm zeugwerk

Troubleshooting

scoop install fails with 401 Unauthorized The token is either missing or incorrect. Verify that private_hosts is configured correctly by checking $HOME\.config\scoop\config.json. Run the bootstrap again with the correct ZEUGWERK_TOKEN.

scoop bucket add fails The Zeugwerk bucket is a private repository. Ensure the machine has network access to github.com and that the GitHub credentials (if required) are available. Contact us if you need access granted.

Hash mismatch on download Scoop verifies the SHA256 hash of every downloaded binary against the manifest. If this fails, the manifest may not have updated yet after a release. Run scoop update to refresh the manifest and retry.

For background on why we chose Scoop for on-premises tool distribution and how the authentication layer works, see the blog post.

Table of Contents