Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions .github/workflows/kit-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,43 @@ jobs:
# catch a syntax error in it before an author ran it against a deck.
python3 -c "import ast,sys; ast.parse(open(sys.argv[1]).read(), sys.argv[1])" tools/extract-pptx-assets.py

# `node --check` is syntax-only: it never resolves an import, which is how
# check-tenant-access.mjs shipped importing '../config/workshop-target.mjs'
# as './workshop-target.mjs' and died with ERR_MODULE_NOT_FOUND on every
# run. Importing the modules for real is not an option -- some execute on
# load and would hit a live tenant from CI -- so the edges are resolved
# statically instead.
- name: Every relative import resolves
run: |
node -e "
const fs = require('node:fs');
const path = require('node:path');
const roots = ['bin', 'src', 'tools'];
const files = [];
const walk = (dir) => {
for (const e of fs.readdirSync(dir, {withFileTypes: true})) {
const full = path.join(dir, e.name);
if (e.isDirectory()) walk(full);
else if (/\.mjs\$/.test(e.name)) files.push(full);
}
};
for (const r of roots) if (fs.existsSync(r)) walk(r);
const failures = [];
for (const file of files) {
const src = fs.readFileSync(file, 'utf8');
for (const m of src.matchAll(/(?:from|import)\s*\(?\s*['\"](\.[^'\"]+)['\"]/g)) {
const target = path.resolve(path.dirname(file), m[1]);
if (!fs.existsSync(target)) failures.push(file + ' -> ' + m[1]);
}
}
if (failures.length) {
console.error('Unresolvable relative imports:');
for (const f of failures) console.error('- ' + f);
process.exit(1);
}
console.log(files.length + ' module(s) checked; every relative import resolves.');
"

- name: CLI responds
run: |
node bin/workshop-kit.mjs --version
Expand Down Expand Up @@ -128,6 +165,92 @@ jobs:
grep -q '{{WORKSHOP_UIPATH_ORG_NAME}}' "$work/downloads/project/AGENTS.md" || { echo 'FAIL: source file was mutated'; exit 1; }
echo 'zip pipeline OK'

# Derivation is the only reason two targets can silently share an app name, so
# the uniqueness guard is tested alongside it. `local` and a hosted target
# normally point at the SAME tenant, which is exactly the colliding shape.
- name: Coded App name derives from productSlug and tenant, uniquely
run: |
set -e
work="$(mktemp -d)"; mkdir -p "$work/config"
# $1 = extra top-level JSON, $2 = local's codedApp body, $3 = growth's
write() {
cat > "$work/config/workshop-targets.json" <<JSON
{"title":"F","tagline":"t","repo":"o/r","docsLabel":"D","defaultTarget":"growth",$1
"targets":{
"local":{"siteUrl":"http://x","baseUrl":"/","workshop":{"uipathOrgName":"o","uipathTenantName":"Workshops","uipathTenantUrl":"u","orchestratorParentFolder":"Shared"},"codedApp":{$2"description":"d"}},
"growth":{"siteUrl":"http://y","baseUrl":"/g/","workshop":{"uipathOrgName":"o","uipathTenantName":"Bellevue_July2026_20260727","uipathTenantUrl":"u","orchestratorParentFolder":"Shared"},"codedApp":{$3"description":"d"}}}}
JSON
}
run() { ( cd "$work" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" codedapp check "$1" 2>&1 ); }

# derives, and normalises underscores + case
write '"productSlug":"ixp",' '"name":"ixp-local",' ''
run growth | grep -q 'Coded App name: ixp-bellevue-july2026-20260727' \
|| { echo 'FAIL: did not derive/normalise'; exit 1; }

# an explicit name always wins
write '"productSlug":"ixp",' '"name":"ixp-local",' '"name":"hand-written",'
run growth | grep -q 'Coded App name: hand-written' || { echo 'FAIL: explicit name ignored'; exit 1; }

# no productSlug and no name is still a missing-field error
write '' '"name":"ixp-local",' ''
run growth 2>&1 | grep -q 'missing required fields: codedApp.name' \
|| { echo 'FAIL: absent name not reported'; exit 1; }

# a derived name over 32 fails, and says it was derived
write '"productSlug":"case-management",' '"name":"cm-local",' ''
out="$(run growth)" && { echo 'FAIL: over-long derived name accepted'; exit 1; }
echo "$out" | grep -q 'derived from productSlug' || { echo 'FAIL: error does not say it was derived'; exit 1; }

# two targets resolving to one name is refused (same tenant, both derived)
cat > "$work/config/workshop-targets.json" <<'JSON'
{"title":"F","tagline":"t","repo":"o/r","docsLabel":"D","defaultTarget":"growth","productSlug":"ixp",
"targets":{
"local":{"siteUrl":"http://x","baseUrl":"/","workshop":{"uipathOrgName":"o","uipathTenantName":"Workshops","uipathTenantUrl":"u","orchestratorParentFolder":"Shared"},"codedApp":{"description":"d"}},
"growth":{"siteUrl":"http://y","baseUrl":"/g/","workshop":{"uipathOrgName":"o","uipathTenantName":"Workshops","uipathTenantUrl":"u","orchestratorParentFolder":"Shared"},"codedApp":{"description":"d"}}}}
JSON
out="$(run growth)" && { echo 'FAIL: colliding app names accepted'; exit 1; }
echo "$out" | grep -q 'both resolve to codedApp.name' || { echo 'FAIL: collision not reported'; exit 1; }
echo 'name derivation OK'

# The 32-char Coded App name limit is enforced in validateTarget, which every
# command path reaches. It matters because `uip codedapp publish` ACCEPTS an
# over-long name and only `deploy` refuses it, leaving an orphan package in
# Orchestrator -- so the failure has to happen locally, before either runs.
- name: Coded App name length is enforced at the 32-char boundary
run: |
set -e
work="$(mktemp -d)"
mkdir -p "$work/config"
write_target() {
cat > "$work/config/workshop-targets.json" <<JSON
{"title":"F","tagline":"t","repo":"o/r","docsLabel":"D","defaultTarget":"local",
"targets":{"local":{"siteUrl":"http://localhost:3000","baseUrl":"/",
"workshop":{"uipathOrgName":"o","uipathTenantName":"t","uipathTenantUrl":"u","orchestratorParentFolder":"Shared"},
"codedApp":{"name":"$1","description":"d"}}}}
JSON
}
n32="$(printf 'a%.0s' $(seq 1 32))"
n33="$(printf 'a%.0s' $(seq 1 33))"

write_target "$n32"
( cd "$work" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" codedapp check >/dev/null 2>&1 ) \
|| { echo 'FAIL: a 32-character name was rejected'; exit 1; }

write_target "$n33"
out="$( cd "$work" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" codedapp check 2>&1 )" && {
echo 'FAIL: a 33-character name was accepted'; exit 1; }
echo "$out" | grep -q '33 characters' || { echo 'FAIL: error does not report the length'; exit 1; }

# init must refuse a slug that would blow the budget in any standard pattern.
slugdir="$(mktemp -d)"
( cd "$slugdir" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" init --product communications-mining >/dev/null 2>&1 ) && {
echo 'FAIL: init accepted a 21-character slug'; exit 1; }
[ -z "$(ls -A "$slugdir")" ] || { echo 'FAIL: init left files behind after rejecting'; exit 1; }
( cd "$slugdir" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" init --product comms-mining >/dev/null 2>&1 ) \
|| { echo 'FAIL: init rejected a 12-character slug'; exit 1; }
echo 'name length rules OK'

# This prune DELETES files from static/downloads/, so it is covered the same
# way. The regression it guards: static/downloads/ is gitignored, so a stale
# ZIP is invisible to CI and code review, yet `codedapp pack` packs the local
Expand Down
127 changes: 123 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ template/ scaffold for `workshop-kit init` (a complete, building
workshop-kit prepare zip:downloads + doc-asset + workshop-var checks + agents build
workshop-kit agents build regenerate AGENTS.md from base + product
workshop-kit agents check fail if AGENTS.md is stale or hand-edited inside the fence
workshop-kit check:tenant-access advisory tenant permission report (never fails a build)
workshop-kit check:tenant-access advisory tenant permission + capacity report (never fails a build)
workshop-kit build --target <name>
workshop-kit codedapp <check|pack|publish|deploy|all> pack prunes old nupkgs
workshop-kit preview --target <name>
Expand All @@ -45,6 +45,113 @@ workshop-kit repin <tag> move a content repo onto a released kit ta
workshop-kit init --product <slug>
```

## The tenant check

`check:tenant-access` answers one question before a workshop is delivered: can
this tenant actually run it? It reports two things.

**Permissions.** Whether the `<tenant>-Participants` and `<tenant>-Facilitators`
groups hold the Document Understanding, Data Fabric, Studio Web and folder roles
the exercises need, and whether the IXP (`reinfer`) service is enabled. For a
missing role it prints the `uip` command that grants it, and never runs it.

`<tenant>-Participants` and `<tenant>-Facilitators` is the UiPath Labs convention,
and it holds for the `uipathlabstraining` tenants that host real deliveries. It does
**not** hold elsewhere: a testing tenant such as `growthuipath/Workshops` uses names
like `Workshop Participants`, `Workshop Trainers` and `Workshops CM-1`, so every
group check there reports "not found" — a naming mismatch that reads as a permission
problem. That is the main reason to gate `requiresTenantAccess` on the tenant a
target actually points at rather than on the target's name.

**Capacity.** AI Unit and Agent Unit headroom in the account, and every IXP quota
the tenant reports. This is the half that catches "we ran out of units halfway
through" and "nobody can create another dataset" on the morning of delivery
rather than during it.

Two notes on how the capacity numbers are read, both of which cost time to
establish:

- Headroom is derived, not read. `Available` is null for consumables in the
licence summary and `Allocated` is what the org handed to tenants, so neither
is the answer. The check subtracts consumption from `TotalUnitsInAccount`.
- The two licence surfaces disagree, so the check reads both and takes the
larger consumption figure. On one org the summary reported 3,675,583 AI Units
consumed against the same 5,000,000 pool that the per-tenant rows summed to
1,796,083 — a 1.9M gap. Trusting the smaller number would have overstated
headroom 2.4x, in the one check whose job is to stop a workshop running out.
The gap is printed rather than hidden.

**IXP quotas come from `re`, not `uip`.** They are a Reinfer concept, and `uip`
cannot see them at all — `uip ixp` has no capacity command, and its project list
returns only a count. `re get quotas` returns every kind with a real
`hard_limit` and `current_max_usage`: `sources`, `datasets`, `buckets`,
`comments`, `comments_per_source`, `integrations`, `triggers_per_dataset`,
`extraction_predictions`. So no ceiling has to be declared — only the
per-participant need.

### Getting `re` credentials to the check

The check finds the `re` context whose endpoint addresses the same org and tenant
as the target, comparing the first two path segments (the endpoints differ only in
a trailing `reinfer_` against `orchestrator_`). Contexts are read from the table
`re config ls` prints, never from the file `re` stores them in — that file holds
tokens.

So the operator sets this up once, with `re`'s own supported command:

```bash
re config add --name <name> --endpoint https://cloud.uipath.com/<org>/<tenant>/reinfer_/ --token <token>
```

This is deliberately the only route. A token could instead live in
`.env.deploy.<target>` and be materialised into a temporary `--config-file` —
that works, and it was tried — but it puts this check in the business of handling
a raw API key, writing it to disk, and depending on `re`'s config file format
staying put. `re config add` is the supported way to hold Reinfer credentials, so
the setup burden stays with the operator. It is a real burden: it is a manual step
per tenant, and without it IXP quotas skip.

### Skips are not warnings

`re` ships separately from `uip` and most people building a workshop site will not
have it. That is a fact about a laptop, not a finding about a tenant, so a missing
`re` — or missing Reinfer credentials — is reported as `SKIP`, counted separately
from warnings, and followed by a short note on how to make it run next time. A
check that warns on every build is a check nobody reads.

### Turning it on

A target runs the check at build time when it sets `requiresTenantAccess`, and
gets pass/warn thresholds instead of a bare readout when it declares `capacity`:

```json
"growth": {
"requiresTenantAccess": true,
"capacity": {
"participants": 25,
"aiUnitsPerParticipant": 2000,
"ixpQuotaPerParticipant": {"datasets": 1, "sources": 2}
}
}
```

Every `capacity` field is optional and defaults to 0, which means "report the
number, do not judge it". So a target that declares nothing still gets the full
readout, and only a target that states what it needs can warn — an unconfigured
repo never warns on a healthy tenant, which is how an advisory check earns being
read. `validate-config` rejects unknown keys inside `capacity`, because
`aiUnitsPerParticipants` — plural, one character off — would otherwise fall back
to 0 and silently switch the AI Unit threshold off. The quota kinds inside
`ixpQuotaPerParticipant` are deliberately *not* a closed set, since a new product
quota kind would then fail every build; instead the check warns at run time when a
declared kind is one the tenant does not report, and lists the kinds it does.

Leave `requiresTenantAccess` off for `local`: an offline build must never depend
on a reachable tenant. With it on, the check runs inside `build --target`, which
means it also runs inside `codedapp pack` and `codedapp all`, since both build
the site first. It cannot fail a deploy — a crash in the check (no `uip` on PATH,
an unreachable tenant) is reported and the build continues.

## Releasing, and repinning consumers

Tag the release and move the major tag:
Expand Down Expand Up @@ -87,9 +194,12 @@ jobs:
```

It runs `agents check`, `validate-config`, `check:doc-assets`,
`check:workshop-vars`, `typecheck`, a build, and `doctor`. Because the kit repo is
private, it needs a `KIT_READ_TOKEN` secret that can read it, so npm can resolve
the dependency.
`check:workshop-vars`, `typecheck`, a build, and `doctor`. The kit repo is public,
so `npm ci` resolves the `github:` dependency with no credentials and nothing
needs to be passed in. The optional `KIT_READ_TOKEN` secret is a leftover from
when the kit was private: `validate.yml` skips its auth step when the secret is
absent, and no repo defines it, so `secrets: inherit` above passes nothing. It
can be dropped from both once you are sure the kit stays public.

`.github/workflows/kit-ci.yml` checks the kit itself, including end-to-end
exercises of the two components that fail expensively: the `AGENTS.md` fence
Expand Down Expand Up @@ -140,6 +250,15 @@ moment you pack a different one, and `publish` is a separate command that runs
against the local file, so that would break pack-now-publish-later. Grouping by
name also guarantees the file the current run just produced survives.

Coded App names must be unique across the whole **organisation**, not merely
within a folder or a tenant: deployed apps share one org-wide `*.uipath.host` URL
space, and `baseUrl` must equal `/<codedApp.name>/`. Deploying a name another
tenant already holds fails with `This app name is already deployed in this
folder`, which names the wrong scope — the conflict is the URL, not the folder.
A repo with no local `.uipath/` state does not fail early either: `publish`
registers a *second* app of the same name in whichever tenant you happen to be
logged into, and only the later `deploy` refuses.

Local packages are build artifacts, not the deliverable: `publish` uploads to
Orchestrator. `.uipath/` and `uipath.json` are gitignored in every content repo
and must never be committed. Files in `.uipath/` that are not named
Expand Down
Loading
Loading