Skip to content

fix(uipath-solution): install the pinned CLI in the CI example - #4985

Open
vlad-uipath wants to merge 2 commits into
mainfrom
fix/uipath-solution-freeze-ci
Open

vlad-uipath wants to merge 2 commits into
mainfrom
fix/uipath-solution-freeze-ci

Conversation

@vlad-uipath

@vlad-uipath vlad-uipath commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Make the uipath-solution CI example install the CLI the repo's freeze pins, check it reads the freeze, then uip update, so the job runs in a frozen repo. Found reviewing the uip config freeze feature: CI is the main use of a frozen .uipath/config.json, but the example ran npm install -g @uipath/cli, which installs the newest CLI (npm latest is a dev build today, 1.208.0-dev.9979). That CLI is off versions.cli, so uip login and every step after it are refused.

Key decisions:

  • The frozen setup is the main example. The steps after checkout are: install versions.cli, uip --version 2>&1 | grep "frozen at", then uip update (exit 1 when the CLI or a pinned tool stays off its pin). The frozen at check comes before uip update because a CLI too old to read the freeze ignores it, and its uip update can move to a newer build that prints frozen at, which would hide the problem.
  • The pin is read into a variable, CLI_PIN=$(node -p "...versions.cli"), and not inline. The inline form npm i -g @uipath/cli@$(node -p ...) breaks when the file is missing: node fails, the line becomes npm i -g @uipath/cli@, and npm installs latest with exit 0 (checked with bash -e, as Actions runs a step). ubuntu-latest (Ubuntu 24.04 image) ships Node 22 and npm 10, so no setup-node step is needed.
  • The pin is read with JSON.parse(readFileSync(...)), not require(), and checked in node before it reaches npm. require() runs a .js/.cjs file as code (a committed symlink config.json -> x.cjs does), and it would also read a value of any type. The check is the CLI's own pin pattern (SemVer, exact version), and a leading BOM is allowed, as the CLI allows it. Without the check, a bad value installs the wrong CLI with no error: undefined gets a 404 only by luck, a tag such as latest installs the newest CLI, and npm also takes npm:<pkg>@<v> aliases and git, tarball and file specs, which install another package. The check does not echo the value. A missing file, bad JSON, a non-string pin and a bad pin all print one line and exit 1, and || exit 1 stops the job with or without -e.
  • No shell: bash: the check runs in node, so the step works the same under bash, sh and dash. The snippet is byte-for-byte the one in UiPath/cli#6245 (docs/reference/versioning.md, "Freezing a CI pipeline"), except that it spells npm install -g like the rest of this example.
  • The note names the commands not to run: npm install -g @uipath/cli / @latest, and uip update --force, which updates past the freeze and rewrites the pins. Off the pin, every command except uip update, uip config, uip tools list, help and uip --version is refused (freezeScopeOf in versionsConfig.ts). It gives the narrow freeze recipe (UIPATH_CLI_DISABLE_VERSION_SYNC=1 uip tools install <TOOL>, then uip config freeze) and says that --all makes uip update install every tool on each run. It also says that uip update installs no skills on a fresh runner, and that one runner holds one freeze at a time. It points to uip config freeze --help / uip update --help and links nothing.
  • Unfrozen fallback: replace the three steps after checkout with one, npm install -g @uipath/cli@<CLI_VERSION>.
  • Studio Web: the CI example is not in a flavor block, so studioweb gets the same text. That is right: it describes a GitHub runner with the npm CLI, not the bundled host CLI. So the skills:test ratchet gets five allow entries with that reason (config, config freeze, tools install, tools list, update in references/pack-and-deploy.md), not a flavor block.
  • Same bug in other skills, fixed in their own PRs of this series: uipath-coded-apps (fix(uipath-coded-apps): stop at a freeze instead of forcing an install #4983), uipath-insights (fix(uipath-insights): run uip update for an unknown investigate command #4978, draft), uipath-rules (fix(uipath-rules): install the pinned CLI or run uip update for an unknown rules command #4977). The CLI's own versioning doc ("Freezing a CI pipeline") had the inline npm i -g @uipath/cli@$(node -p ...) form; UiPath/cli#6245 replaces it with the same snippet as here. Not covered: the uipath-coded-apps CI/CD recipe (pack-publish-deploy.md ~:368) has no install step at all.

No GitHub run, no real login. Each step was run locally, as the job runs it.

Setup: P=~/Work/freeze-proof/S7, with an isolated HOME and npm prefix under $P. uip is a shell function that calls $P/prefix/bin/uip, never a global CLI. $P/repo is the checked-out repo: a solution MySolution with one API workflow project, and the committed .uipath/config.json: CLI pin 1.208.0-dev.9872, core.updateChannel: dev, solution-tool and api-workflow-tool at 1.208.0-dev.9872. Each run starts like a fresh runner: no CLI, no tools, empty HOME. The new first step is in $P/scripts/install-step.sh, copied from the YAML, and runs with bash -e. Both sections run the same check after their steps. uip login uses a fake app (x/y), so after the fix it reaches the identity server, which rejects it, with no tenant call. pack is a real offline pack with --profile s7-proof, a profile with no login.

run "uip --version 2>&1"
run "uip login --client-id x --client-secret y --tenant DefaultTenant --profile s7-proof --output json"
run "uip solution pack ./MySolution ./output --version 1.0.1 --output json --profile s7-proof"

Reproduce issue

Old step: npm install -g @uipath/cli. It installs 1.208.0-dev.9979, and uip login and pack are refused.

### step: the old install step
$ npm install -g @uipath/cli
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.

added 38 packages in 6s
[exit 0]
### check
$ uip --version 2>&1
frozen at 1.208.0-dev.9872
1.208.0-dev.9979
[exit 0]
$ uip login --client-id x --client-secret y --tenant DefaultTenant --profile s7-proof --output json
{
  "Result": "Failure",
  "Message": "This CLI is 1.208.0-dev.9979, but this config freezes the CLI at 1.208.0-dev.9872, so the command was not run.",
  "Instructions": "Run 'uip update' to install 1.208.0-dev.9872.",
  "ErrorCode": "configuration_error",
  "Retry": "RetryWillNotFix"
}
[exit 1]
$ uip solution pack ./MySolution ./output --version 1.0.1 --output json --profile s7-proof
{
  "Result": "Failure",
  "Message": "This CLI is 1.208.0-dev.9979, but this config freezes the CLI at 1.208.0-dev.9872, so the command was not run.",
  "Instructions": "Run 'uip update' to install 1.208.0-dev.9872.",
  "ErrorCode": "configuration_error",
  "Retry": "RetryWillNotFix"
}
[exit 1]

Fix validation

New steps: pinned install, frozen at check, uip update. The CLI is on its pin, uip update installs both tools on theirs, uip login gets past the freeze (and fails only on the fake app), and pack builds the package. Pack warnings trimmed: they are the same no-login lines on both runs.

### step: the new install steps
$ bash -e $P/scripts/install-step.sh
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.

added 38 packages in 4s
[exit 0]
$ uip --version 2>&1 | grep "frozen at"
frozen at 1.208.0-dev.9872
[exit 0]
$ uip update
{
  "Result": "Success",
  "Code": "UpdateResult",
  "Data": {
    "DryRun": false,
    "Channel": "dev",
    "Cli": {
      "Current": "1.208.0-dev.9872",
      "Available": null,
      "Action": "none",
      "Reason": "on the CLI pin 1.208.0-dev.9872; newer versions were not looked up, because the pin is exact"
    },
    "Tools": [
      {
        "Name": "api-workflow-tool",
        "To": "1.208.0-dev.9872",
        "Reason": "Installed at its frozen version.",
        "Status": "updated"
      },
      {
        "Name": "solution-tool",
        "To": "1.208.0-dev.9872",
        "Reason": "Installed at its frozen version.",
        "Status": "updated"
      }
    ],
    "Skills": null,
    "Errors": [],
    "HasFailures": false
  }
}
[exit 0]
### check
$ uip --version 2>&1
frozen at 1.208.0-dev.9872
1.208.0-dev.9872
[exit 0]
$ uip login --client-id x --client-secret y --tenant DefaultTenant --profile s7-proof --output json
{
  "Result": "AuthenticationError",
  "Message": "Client Credentials authentication failed (400)\nError: invalid_client\nDetails: Unknown error\n\nTroubleshooting:\n  • Verify your Client ID is correct\n  • Ensure your Client Secret hasn't expired\n  • Check that the external application is enabled in UiPath\n  • Confirm you're using the correct authority URL",
  "Instructions": "See message above for details. Headless? Set UIPATH_CLI_ENABLE_ENV_AUTH=true with UIPATH_CLI_AUTH_TOKEN, UIPATH_CLI_ORGANIZATION_NAME, UIPATH_CLI_ORGANIZATION_ID, UIPATH_CLI_TENANT_NAME, and UIPATH_CLI_TENANT_ID to skip the browser flow.",
  "Context": {
    "HttpStatus": 400
  },
  "ErrorCode": "authentication_required",
  "Retry": "RetryWillNotFix"
}
[exit 2]
$ uip solution pack ./MySolution ./output --version 1.0.1 --output json --profile s7-proof
{
  "Result": "Success",
  "Code": "SolutionPack",
  "Data": {
    "Package": "MySolution@1.0.1",
    "Packages": "$P/repo/output/MySolution_1.0.1.zip"
  }
}
[exit 0]

The end-to-end run above used the earlier version of the first step (require() plus a bash [[ =~ ]] check). For a valid pin the current step installs the same spec. The current step, taken out of the YAML with a YAML parser and run with a stub npm that prints its arguments, on six committed configs. symlink is .uipath/config.json -> evil.cjs, a file that writes MARKER when it runs (checked: node -e 'require("./evil.cjs")' writes it).

$ for sh in bash sh; do for c in valid bom array alias missing symlink; do echo "### $sh $c"; (cd $c && $sh ../step.sh 2>&1; echo "[exit $?]"); done; done
### bash valid
npm install -g @uipath/cli@1.208.0-dev.9872
[exit 0]
### bash bom
npm install -g @uipath/cli@1.207.1
[exit 0]
### bash array
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
### bash alias
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
### bash missing
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
### bash symlink
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
### sh valid
npm install -g @uipath/cli@1.208.0-dev.9872
[exit 0]
### sh bom
npm install -g @uipath/cli@1.207.1
[exit 0]
### sh array
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
### sh alias
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
### sh missing
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
### sh symlink
versions.cli in .uipath/config.json is missing or not an exact version
[exit 1]
$ ls MARKER
ls: MARKER: No such file or directory

array is {"versions":{"cli":["1.207.1"]}} and alias is "npm:evil@1.0.0". /bin/dash gives the same six results. On macOS sh is bash in POSIX mode, so dash is the real non-bash shell here.

Repo checks:

  • After the rebase: node --test tests/scripts/studioweb-browser-commands.test.mjs 20/20, npm run skills:validate OK, check-skill-links.mjs OK, the pre-commit description check OK. check-sensitive-content.py --strict reports two findings, both in asset snapshot files this PR does not touch.
  • Before the rebase: npm run skills:test: the studioweb ratchet test passes. 2 of 483 tests fail: pack builds complete, marker-free default and custom npm packages and root npm pack emits one marker-free default package and restores canonical sources. The same 2 fail on a clean origin/main checkout on this machine (an npm publish --dry-run exit and a tarball hash), so they are local, not caused by this change.
  • npm run skills:validate and npm run skills:build: OK. The CI section in build/skills/default and build/skills/studioweb is identical to the source.
  • python3 scripts/check-skill-verbs.py: the same 6 stale findings as main, none in this change. node scripts/check-skill-links.mjs: OK.

Known limits:

  • Not run on GitHub Actions. Node on ubuntu-latest is from the runner image's README.
  • restore, publish and deploy run need a real login and were not run.
  • The freeze recipes (touch, UIPATH_CLI_DISABLE_VERSION_SYNC=1 uip tools install solution/api-workflow, uip config freeze, and --all) were run once in the isolated env. They wrote the pins to the repo's file. Not shown above.
  • The unfrozen fallback was not run.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @vlad-uipath's task in 1m 20s —— View job


Summary

Changes the uipath-solution GitHub Actions example so it installs the CLI version pinned in the repo's .uipath/config.json, checks that this CLI reads the freeze (frozen at), and runs uip update before uip login. Adds a note on how to create the freeze, with its security caveats and the commands not to run. Also adds four studioweb ratchet allow entries for the new verbs.

Change-by-Change Review

1. skills/uipath-solution/references/pack-and-deploy.md:456-461: install steps

OK

  • The run: | # comment block scalar with a trailing comment is valid YAML. On ubuntu-latest, a step with no shell: runs as bash -e {0}, so [[ … =~ … ]] works.
  • Reading the pin into CLI_PIN before npm sees it is right. Without that, a missing file makes the spec @uipath/cli@, which installs latest and exits 0.
  • The regex check is sound. It rejects anything containing :, /, @ or +, so npm aliases (npm:), git, tarball and file specs, and tags cannot get through. It also rejects undefined. Values like 1.2.3-- still match, but npm rejects those itself, so they are harmless.
  • uip --version 2>&1 | grep "frozen at": without pipefail, the step's exit code is grep's, which is what you want here. It is also right to run this check before uip update, for the reason the PR gives.
  • uip update has no --output json. That is fine because nothing parses its output.

2. skills/uipath-solution/references/pack-and-deploy.md:469: freeze note

Medium (LLM usability / content-quality)
The content is correct and the security points are valuable (the auth.authority trust boundary, the CODEOWNERS advice, --force rewriting the pins). The problem is the shape. It is one paragraph of about 380 words that mixes:

  • a 4-step setup recipe (install the pinned CLI, touch the config, tools install with UIPATH_CLI_DISABLE_VERSION_SYNC=1, config freeze, then commit),
  • a trust/review rule,
  • three anti-patterns (npm i -g @uipath/cli/@latest, uip update --force, sharing one self-hosted runner between freezes),
  • other facts (--all pins every tool, no skills get installed).

.claude/rules/content-quality.md asks for numbered lists for sequential steps and an explicit "What NOT to do" section. Agents follow those much more reliably than inline prose, and these commands are expensive to get wrong: a wrong npm install blocks every later step. Suggested split, same facts:

  1. Create the freeze (once, on a dev machine, inside the repo): a numbered list of the 4–5 steps, each command in backticks.
  2. Trust: one sentence on auth.authority plus the CODEOWNERS advice.
  3. Do not: bullets for npm install -g @uipath/cli / @latest, uip update --force, and two jobs with different pins on one self-hosted runner.

Fix this →

Minor (Low): the prose uses second person ("your home config", "you chose") and some filler ("for one", "Read the file before you commit it: everything in it goes into the repo"). .claude/rules/token-optimization.md asks for terser wording.

3. skills/uipath-solution/references/pack-and-deploy.md:471: unfrozen fallback

OK. It uses the <CLI_VERSION> placeholder and pins an exact version, so it no longer installs latest.

4. tests/scripts/studioweb-browser-commands.json

OK. Using allow instead of a flavor block is justified: the text is about a GitHub runner with the npm CLI, which is the same for studioweb users. I checked skill-flavors/studioweb/uipath-solution/references/pack-and-deploy.md, and the CI section is not in a replaced block, so studioweb gets this edit. The four entries repeat the same reason text, which is acceptable for this file's format.

What's Missing

  • No coder_eval task covers the CI example. That is acceptable for a doc fix, but a small smoke task would catch a regression to an unpinned npm install -g @uipath/cli. Optional; Low.
  • Nothing else identified. The change stays within the skill, has no cross-skill links, adds no relative links that could break, and contains no secrets or personal paths (the ~/Work/freeze-proof path appears only in the PR body, not in committed files).

Area Ratings

Area Status Notes
Frontmatter OK Unchanged
E2E Tests OK No new capability that needs a task; optional smoke task above
Skill Body OK Unchanged
References & Assets Issue Freeze note is one paragraph of about 380 words; split into steps and "Do not" bullets
Repo Hygiene OK Scoped; ratchet entries justified

Issues for Manual Review

  • config freeze is missing from assets/uip-catalog-snapshot.json; only update is there. The snapshot is probably older than the freeze feature. The PR reports no new check-skill-verbs.py findings, but someone should confirm that uip config freeze, uip config freeze --all, UIPATH_CLI_DISABLE_VERSION_SYNC and the frozen at line in uip --version output are on the CLI's stable/public surface, not dev-build only. If they are dev-only, this text is ahead of the released CLI.
  • Confirm that require() of the empty .uipath/config.json created by touch never runs in CI. It throws, which fails the step correctly, but only if the dev forgets to run uip config freeze before committing.
  • The PR body says this was not run on GitHub Actions. Running the job once on a throwaway repo would confirm the bash -e default shell and that Node is present on the runner image.

Conclusion

Approve with a suggestion. The fix is correct and better hardened than the CLI's own documented recipe: it validates the pin before npm sees it, fails loudly when the file is missing, and checks the freeze before uip update. The only thing worth changing before merge is to break the freeze note into a numbered recipe and a "Do not" list.

@vlad-uipath
vlad-uipath force-pushed the fix/uipath-solution-freeze-ci branch 2 times, most recently from 1c8e6f6 to b561086 Compare November 19, 2026 14:46
vlad-uipath and others added 2 commits November 19, 2026 22:38
In a repo that commits a frozen .uipath/config.json, `npm install -g @uipath/cli`
installs the newest CLI, which is off the CLI pin, so `uip login` and every later
step are refused. Install versions.cli, run `uip update` and check for the
`frozen at` line. Without a freeze, install one exact version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The pin step now reads .uipath/config.json with JSON.parse instead of
require(), so a symlinked or renamed file never runs as code, and checks
the pin in node with the CLI's own pattern. It works the same under bash
and sh, so the step no longer needs shell: bash. The snippet matches the
one in the CLI's versioning doc.

The freeze note also lists help, --version and uip tools list among the
commands that still run off the pin.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vlad-uipath
vlad-uipath force-pushed the fix/uipath-solution-freeze-ci branch from b561086 to 576564a Compare November 19, 2026 20:40

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant