Quickstart

This guide installs the CLI and adds two workflows to a repository. It takes a few minutes.

1. Install the CLI

Install the latest release from PyPI with uv:

uv tool install ghwm

To pin the CLI to the current release instead, for reproducible setups:

uv tool install ghwm==1.12.0

Prefer another tool? Use pipx install ghwm or pip install ghwm.

2. Authenticate with GitHub

ghwm downloads workflow packages from GitHub Packages, which requires a GitHub token even when the registry is public. The token needs the read:packages scope. Either sign in with the GitHub CLI:

gh auth login
gh auth refresh -s read:packages

or export a token that has the scope, as GH_TOKEN or GITHUB_TOKEN. In GitHub Actions, use GITHUB_TOKEN with packages: read.

3. Create `ghwm.yml`

Add this file to the root of your repository:

ghwm.yml

source: ghwfxlab/ghwm-registry
workflows:
  - name: super-linter
    version: 2.0.1
  - name: auto-assign-pr
    version: 1.0.2
    update-triggers: true
    update-config-files: true

source is the registry repository, and each workflow needs a name and an exact version. Per-workflow options such as update-triggers and update-config-files are described in the manifest reference.

4. Install the workflows

ghwm install

Commit the files it generates, including ghwm.lock. Some workflows need secrets or variables; check each package's page in the registry for its setup.

5. Update workflows

Bump the version in ghwm.yml, then refresh:

ghwm.yml (diff)

workflows:
  - name: super-linter
-    version: 2.0.1
+    version: 2.1.0

ghwm update

6. Remove a workflow

Delete its entry from ghwm.yml and run ghwm install. See the ghwm CLI readme for all commands and pruning options.

7. Keep versions current with Renovate

Add the preset to renovate.json to receive pull requests when new package versions ship:

renovate.json

{
  "extends": ["github>ghwfxlab/ghwm-registry//renovate/default.json"]
}

Custom registries

You are not limited to this registry. The source key in ghwm.yml names the registry repository in owner/repository format, and packages are resolved from GitHub Packages as @owner/name. To create your own, fork the ghwm-registry repository and add packages to it; see Writing a package for the layout.

To pull one workflow from a different registry, override source on that entry: