Skip to content

setup-guide.md

Latest commit

 

History

History
129 lines (85 loc) · 3.54 KB

setup-guide.md

File metadata and controls

129 lines (85 loc) · 3.54 KB
Raw

Setup Guide

End-to-end setup for the Bulk Copy Stories Between Iterations widget — auth, dev harness, and deploy. Adapted from the wsjf-grid setup guide.

This widget writes to Rally. In live mode it creates new user stories (and tasks) in your workspace. Always test with a non-production project before deploying to customers.

Prerequisites

  • Node 18+ and npm
  • A Rally workspace and project you can access
  • A Rally API key (instructions below)

1. Generate a Rally API key

  1. Sign in to Rally.
  2. Open the API key page: https://rally1.rallydev.com/#/api_key (or click your avatar → API Keys).
  3. Click Create, give the key a name (e.g. widget-dev), pick the workspaces it can access, and copy the full key. It starts with _ and is ~43 chars long.
  4. Treat it like a password — don't paste it into anything that gets committed.

2. Configure auth (pick one)

Option A — auth.json (per-widget, gitignored)

Create auth.json in the widget folder:

{
  "server": "https://rally1.rallydev.com",
  "apiKey": "_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

auth.json is in the root .gitignore, so it never gets committed.

Option B — environment variables

export RALLY_SERVER=https://rally1.rallydev.com
export RALLY_API_KEY=_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Or drop a .env.local in the widget folder:

RALLY_SERVER=https://rally1.rallydev.com
RALLY_API_KEY=_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Restart npm run dev after changing credentials.

3. Run the dev server

npm run dev

Opens at http://localhost:5175. By default, mock data is used.

Append ?live=true to load real Rally data:

http://localhost:5175?live=true

4. Mock mode

The dev server defaults to mock mode (no Rally connection needed). The mock scenario includes:

  • Iteration A — 5 stories (SSO, password reset, session timeout, RBAC, audit log)
  • Iteration B — 3 stories (dashboard perf, CSV export, bulk delete)
  • Iteration C — 2 stories (mobile layout, offline mode)

copyStories in mock mode simulates network delay (200ms/story) and logs the operation without persisting to Rally. The result summary shows new mock FormattedIDs (US9000, US9001, …).

5. Deploy to Rally

npx widget-ai deploy

What it does:

  1. Runs vite build — emits a single dist/app.js IIFE with all styles inlined.
  2. Wraps it in a minimal HTML doc that loads React from a CDN.
  3. Reads rally.config.json for the widget name and target workspace.
  4. Reads auth.json for credentials.
  5. Creates or updates the Custom HTML Widget in Rally.
  6. Prints the Rally URL.

The created/updated view ID is written back into rally.config.json so subsequent deploys hit the same target.

Common deploy issues

  • No auth.json found — create one before running widget-ai deploy.
  • 401 Unauthorized from Rally — API key is revoked. Generate a new one.
  • dist/app.js not found — run npm run build and check for errors first.

6. Iterate

Task Command
Edit a component src/App.tsx — Vite hot-reloads on save
Open the settings UI DevHarness → Gear button
Production build npm run build
Mock/demo build npm run build:mock
Deploy to Rally npx widget-ai deploy

Reference