docs: improve local development setup documentation#2783
Conversation
The Quick Start in README omitted critical prerequisites (PostgreSQL, GitHub App credentials), causing new contributors to hit errors immediately. Fix by listing real prerequisites, correcting the commands, and adding a step-by-step setup guide to CONTRIBUTING.md. Reorganize .env.example with clear required/optional sections. Closes #2781 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Finished running flow.
|
||||||||||||||||||
|
📝 WalkthroughWalkthroughDocumentation and configuration updates: Quick Start simplified, CONTRIBUTING expanded with local development setup and prerequisites, and Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/studio.giselles.ai/.env.example`:
- Around line 12-16: Reorder the dotenv keys to satisfy dotenv-linter by
arranging the GITHUB_APP_* entries alphabetically; replace the current block
(GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_CLIENT_ID,
GITHUB_APP_CLIENT_SECRET, GITHUB_APP_WEBHOOK_SECRET) with the alphabetized
sequence: GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_ID,
GITHUB_APP_PRIVATE_KEY, GITHUB_APP_WEBHOOK_SECRET so the linter passes.
- Around line 18-30: The OPENAI_API_KEY declaration currently sits above the
"Optional" block and contradicts the comment that "At least one AI provider API
key is needed"; either move the OPENAI_API_KEY line into the optional providers
section alongside ANTHROPIC_API_KEY and GOOGLE_AI_API_KEY or update the header
comment to explicitly state OpenAI is required; update the surrounding comments
so they consistently reflect the chosen behavior and ensure OPENAI_API_KEY,
ANTHROPIC_API_KEY and GOOGLE_AI_API_KEY are grouped with matching explanatory
text.
In `@CONTRIBUTING.md`:
- Around line 64-67: Replace the inconsistent npx command in the CONTRIBUTING.md
snippet: find the exact text "npx drizzle-kit push" and change it to "pnpm exec
drizzle-kit push" so the migration step uses the project's pnpm toolchain and
matches other setup commands; ensure spacing and surrounding lines (the cd
commands) remain unchanged.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.continuity/20260303-120000-main.mdCONTRIBUTING.mdREADME.mdapps/studio.giselles.ai/.env.example
| GITHUB_APP_ID= | ||
| GITHUB_APP_PRIVATE_KEY= | ||
| GITHUB_APP_CLIENT_ID= | ||
| GITHUB_APP_CLIENT_SECRET= | ||
| GITHUB_APP_WEBHOOK_SECRET= |
There was a problem hiding this comment.
Fix dotenv key ordering to satisfy current linter rule.
dotenv-linter flagged the GitHub App key order. If lint is CI-gated, this can fail checks; reorder keys per rule.
🧰 Tools
🪛 dotenv-linter (4.0.0)
[warning] 14-14: [UnorderedKey] The GITHUB_APP_CLIENT_ID key should go before the GITHUB_APP_ID key
(UnorderedKey)
[warning] 15-15: [UnorderedKey] The GITHUB_APP_CLIENT_SECRET key should go before the GITHUB_APP_ID key
(UnorderedKey)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/studio.giselles.ai/.env.example` around lines 12 - 16, Reorder the
dotenv keys to satisfy dotenv-linter by arranging the GITHUB_APP_* entries
alphabetically; replace the current block (GITHUB_APP_ID,
GITHUB_APP_PRIVATE_KEY, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET,
GITHUB_APP_WEBHOOK_SECRET) with the alphabetized sequence: GITHUB_APP_CLIENT_ID,
GITHUB_APP_CLIENT_SECRET, GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY,
GITHUB_APP_WEBHOOK_SECRET so the linter passes.
| # At least one AI provider API key is needed to use text generation | ||
| # OpenAI API https://openai.com/index/openai-api/ | ||
| # @see https://platform.openai.com/docs/quickstart | ||
| OPENAI_API_KEY= | ||
|
|
||
| # ============================================================================== | ||
| # Optional — features will degrade gracefully without these | ||
| # ============================================================================== | ||
|
|
||
| # Additional AI providers | ||
| # ANTHROPIC_API_KEY= | ||
| # GOOGLE_AI_API_KEY= | ||
|
|
There was a problem hiding this comment.
OPENAI_API_KEY placement conflicts with “at least one provider” requirement.
This currently reads as “OpenAI is required,” while the comment says any single provider key is enough. Move OPENAI_API_KEY to the optional provider block (or explicitly document OpenAI-only requirement).
Suggested `.env.example` adjustment
-# At least one AI provider API key is needed to use text generation
-# OpenAI API https://openai.com/index/openai-api/
-# `@see` https://platform.openai.com/docs/quickstart
-OPENAI_API_KEY=
+# At least one AI provider API key is needed to use text generation
# ==============================================================================
# Optional — features will degrade gracefully without these
# ==============================================================================
# Additional AI providers
-# ANTHROPIC_API_KEY=
-# GOOGLE_AI_API_KEY=
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GOOGLE_AI_API_KEY=📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # At least one AI provider API key is needed to use text generation | |
| # OpenAI API https://openai.com/index/openai-api/ | |
| # @see https://platform.openai.com/docs/quickstart | |
| OPENAI_API_KEY= | |
| # ============================================================================== | |
| # Optional — features will degrade gracefully without these | |
| # ============================================================================== | |
| # Additional AI providers | |
| # ANTHROPIC_API_KEY= | |
| # GOOGLE_AI_API_KEY= | |
| # At least one AI provider API key is needed to use text generation | |
| # ============================================================================== | |
| # Optional — features will degrade gracefully without these | |
| # ============================================================================== | |
| # Additional AI providers | |
| # OPENAI_API_KEY= | |
| # ANTHROPIC_API_KEY= | |
| # GOOGLE_AI_API_KEY= |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/studio.giselles.ai/.env.example` around lines 18 - 30, The
OPENAI_API_KEY declaration currently sits above the "Optional" block and
contradicts the comment that "At least one AI provider API key is needed";
either move the OPENAI_API_KEY line into the optional providers section
alongside ANTHROPIC_API_KEY and GOOGLE_AI_API_KEY or update the header comment
to explicitly state OpenAI is required; update the surrounding comments so they
consistently reflect the chosen behavior and ensure OPENAI_API_KEY,
ANTHROPIC_API_KEY and GOOGLE_AI_API_KEY are grouped with matching explanatory
text.
| ```bash | ||
| cd apps/studio.giselles.ai | ||
| npx drizzle-kit push | ||
| cd ../.. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# 1. Check package.json for drizzle scripts and dependencies
echo "=== Checking package.json for drizzle-related scripts ==="
rg -n 'drizzle|scripts' package.json -A 5 -B 5 | head -100
# 2. Verify drizzle-kit is in pnpm-lock.yaml
echo -e "\n=== Checking pnpm-lock.yaml for drizzle-kit ==="
rg -n 'drizzle-kit' pnpm-lock.yaml | head -10
# 3. View exact content of CONTRIBUTING.md around lines 64-67
echo -e "\n=== CONTRIBUTING.md lines 60-70 ==="
sed -n '60,70p' CONTRIBUTING.mdRepository: giselles-ai/giselle
Length of output: 2042
🏁 Script executed:
#!/bin/bash
# 4. Search for other drizzle-kit usage in the codebase
echo "=== Searching for drizzle-kit usage patterns ==="
rg -n 'drizzle-kit' --type md --type ts --type tsx --type js --type json -C 2
# 5. Check if there's a workspace or app-specific package.json
echo -e "\n=== Checking apps/studio.giselles.ai/package.json ==="
if [ -f apps/studio.giselles.ai/package.json ]; then
rg -n '"scripts"|drizzle' apps/studio.giselles.ai/package.json -A 3 -B 3
fiRepository: giselles-ai/giselle
Length of output: 849
🏁 Script executed:
#!/bin/bash
# Check for other npx usages in CONTRIBUTING.md to see if pattern is consistent
echo "=== Searching for 'npx' in CONTRIBUTING.md ==="
rg -n 'npx' CONTRIBUTING.md
# Check full scripts section in apps/studio.giselles.ai/package.json
echo -e "\n=== Full scripts section in apps/studio.giselles.ai/package.json ==="
sed -n '9,30p' apps/studio.giselles.ai/package.jsonRepository: giselles-ai/giselle
Length of output: 955
Use pnpm exec for database migrations in setup docs.
The documentation at line 66 uses npx drizzle-kit push, which is inconsistent with the project's pnpm-exclusive toolchain (as specified in packageManager: "pnpm@10.16.0"). Update to pnpm exec drizzle-kit push to align with project standards and all other setup commands.
Suggested docs change
cd apps/studio.giselles.ai
-npx drizzle-kit push
+pnpm exec drizzle-kit push
cd ../..🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CONTRIBUTING.md` around lines 64 - 67, Replace the inconsistent npx command
in the CONTRIBUTING.md snippet: find the exact text "npx drizzle-kit push" and
change it to "pnpm exec drizzle-kit push" so the migration step uses the
project's pnpm toolchain and matches other setup commands; ensure spacing and
surrounding lines (the cd commands) remain unchanged.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 12798587fe
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # Optional — features will degrade gracefully without these | ||
| # ============================================================================== |
There was a problem hiding this comment.
Labeling the rest of this file as optional is misleading for COOKIE_SECRET: if a developer follows this guidance and leaves it empty, authenticated pages will crash because getGiselleSession() calls getCookie(), and lib/signed-cookie.ts hard-fails with invariant(SECRET, "COOKIE_SECRET is not set"). This is not graceful degradation; it blocks normal logged-in flows (for example, paths that call fetchCurrentTeam() in the main app UI), so COOKIE_SECRET should be documented as required alongside the other boot-time essentials.
Useful? React with 👍 / 👎.
🔍 QA Testing Assistant by Giselle📋 Manual QA ChecklistBased on the changes in this PR, here are the key areas to test manually:
✨ Prompt for AI AgentsUse the following prompts with Cursor or Claude Code to automate E2E testing: 📝 E2E Test Generation Prompt
4. MCP Integration Guidelines
5. CI-Ready Code Requirements
|
There was a problem hiding this comment.
Pull request overview
This PR updates contributor-facing documentation to reduce “surprise” setup failures when running the Studio app locally, by making prerequisites explicit and providing a clearer end-to-end setup path.
Changes:
- Reworks
README.mdQuick Start commands to match the current monorepo scripts and points readers to full setup docs. - Adds a step-by-step local development setup guide to
CONTRIBUTING.md(prereqs, env vars, DB setup, migrations, dev server). - Reorganizes
apps/studio.giselles.ai/.env.exampleinto clearer Required vs Optional sections and promotes GitHub App credentials to the required set.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| apps/studio.giselles.ai/.env.example | Reorganizes env vars into Required/Optional blocks and promotes core variables. |
| README.md | Updates Quick Start commands and calls out prerequisites + link to CONTRIBUTING setup guide. |
| CONTRIBUTING.md | Adds a numbered local dev setup guide with prerequisites, env vars, DB + migrations. |
| .continuity/20260303-120000-main.md | Adds a continuity ledger entry describing intent/decisions for this doc-focused change. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # ============================================================================== | ||
| # Required — the app will not start without these | ||
| # ============================================================================== |
There was a problem hiding this comment.
The file declares “Required — the app will not start without these”, but COOKIE_SECRET is not included in the required section even though core request paths call signed-cookie (which hard-throws if COOKIE_SECRET is unset). Please move COOKIE_SECRET into the Required section (and keep the later entry consistent) so new contributors don’t miss it.
|
|
||
| # Additional AI providers | ||
| # ANTHROPIC_API_KEY= | ||
| # GOOGLE_AI_API_KEY= |
There was a problem hiding this comment.
The suggested Google/other provider env var names don’t match what the code reads. For embeddings, the code checks GOOGLE_GENERATIVE_AI_API_KEY (not GOOGLE_AI_API_KEY) and also uses COHERE_API_KEY for Cohere profiles. Please update these names in .env.example (and consider adding AI_GATEWAY_API_KEY as an optional entry since it’s referenced as well).
| # GOOGLE_AI_API_KEY= | |
| # GOOGLE_GENERATIVE_AI_API_KEY= | |
| # COHERE_API_KEY= | |
| # AI_GATEWAY_API_KEY= |
| Open [http://localhost:3000](http://localhost:3000) and start building your AI agents! | ||
|
|
||
| > **Note**: You need at least one AI provider API key. Supported providers: OpenAI, Anthropic, Google AI. | ||
| > **Note**: You need Node.js 24+, pnpm 10+, PostgreSQL, a GitHub App, and at least one AI provider API key. Edit `.env.local` before starting — see [CONTRIBUTING.md](CONTRIBUTING.md#development-environment-setup) for full setup instructions. |
There was a problem hiding this comment.
The note says to edit .env.local, but the Quick Start creates apps/studio.giselles.ai/.env.local. Please point to the full path to avoid contributors editing/creating a root-level .env.local by mistake.
| > **Note**: You need Node.js 24+, pnpm 10+, PostgreSQL, a GitHub App, and at least one AI provider API key. Edit `.env.local` before starting — see [CONTRIBUTING.md](CONTRIBUTING.md#development-environment-setup) for full setup instructions. | |
| > **Note**: You need Node.js 24+, pnpm 10+, PostgreSQL, a GitHub App, and at least one AI provider API key. Edit `apps/studio.giselles.ai/.env.local` before starting — see [CONTRIBUTING.md](CONTRIBUTING.md#development-environment-setup) for full setup instructions. |
| | `GITHUB_APP_ID` | Your GitHub App's ID | | ||
| | `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) | | ||
| | `GITHUB_APP_CLIENT_ID` | Your GitHub App's client ID | | ||
| | `GITHUB_APP_CLIENT_SECRET` | Your GitHub App's client secret | | ||
| | `GITHUB_APP_WEBHOOK_SECRET` | Your GitHub App's webhook secret | | ||
|
|
There was a problem hiding this comment.
This “required variables” list is missing COOKIE_SECRET, which is required for signed session cookies (signed-cookie hard-throws when it’s unset). Please include it in the required variables table so local setup doesn’t fail at runtime.
| | `GITHUB_APP_ID` | Your GitHub App's ID | | |
| | `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) | | |
| | `GITHUB_APP_CLIENT_ID` | Your GitHub App's client ID | | |
| | `GITHUB_APP_CLIENT_SECRET` | Your GitHub App's client secret | | |
| | `GITHUB_APP_WEBHOOK_SECRET` | Your GitHub App's webhook secret | | |
| | `COOKIE_SECRET` | Secret used to sign session cookies (required for signed-cookie) | | |
| | `GITHUB_APP_ID` | Your GitHub App's ID | | |
| | `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) | | |
| | `GITHUB_APP_CLIENT_ID` | Your GitHub App's client ID | | |
| | `GITHUB_APP_CLIENT_SECRET` | Your GitHub App's client secret | | |
| | `GITHUB_APP_WEBHOOK_SECRET` | Your GitHub App's webhook secret | |
| |----------|----------| | ||
| | `OPENAI_API_KEY` | OpenAI | | ||
| | `ANTHROPIC_API_KEY` | Anthropic | | ||
| | `GOOGLE_AI_API_KEY` | Google AI | |
There was a problem hiding this comment.
The Google provider env var name here (GOOGLE_AI_API_KEY) doesn’t match what the codebase expects for Gemini embeddings (GOOGLE_GENERATIVE_AI_API_KEY). Please update the variable name (and consider mentioning COHERE_API_KEY if Cohere embedding profiles are used locally).
| | `GOOGLE_AI_API_KEY` | Google AI | | |
| | `GOOGLE_GENERATIVE_AI_API_KEY` | Google AI (Gemini) | | |
| | `COHERE_API_KEY` | Cohere | |
| |----------|-------------| | ||
| | `POSTGRES_URL` | PostgreSQL connection string (e.g. `postgres://user:pass@localhost:5432/giselle`) | | ||
| | `GITHUB_APP_ID` | Your GitHub App's ID | | ||
| | `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) | |
There was a problem hiding this comment.
GITHUB_APP_PRIVATE_KEY is described as “PEM format”, but .env.local typically can’t safely store a raw multi-line PEM without converting newlines (e.g., replacing line breaks with \n). Consider adding a short note about the expected formatting so new contributors don’t paste a multi-line key that dotenv parses incorrectly.
| | `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key (PEM format) | | |
| | `GITHUB_APP_PRIVATE_KEY` | Your GitHub App's private key in PEM format, with line breaks replaced by `\n` so it fits on a single line in `.env.local` | |
There was a problem hiding this comment.
♻️ Duplicate comments (1)
CONTRIBUTING.md (1)
64-68:⚠️ Potential issue | 🟡 MinorUse
pnpm execfor consistency with project toolchain.Line 66 uses
npx drizzle-kit push, which is inconsistent with the project's pnpm-exclusive package manager. All other commands in this guide usepnpm, and the project specifiespackageManager: "pnpm@10.16.0".Suggested fix
cd apps/studio.giselles.ai -npx drizzle-kit push +pnpm exec drizzle-kit push cd ../..🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CONTRIBUTING.md` around lines 64 - 68, Replace the inconsistent use of npx in the CONTRIBUTING.md snippet: change the command that currently runs "npx drizzle-kit push" to use the project's pnpm toolchain, e.g., run "pnpm exec drizzle-kit push" so it aligns with the packageManager and other docs; update the line referencing "npx drizzle-kit push" accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@CONTRIBUTING.md`:
- Around line 64-68: Replace the inconsistent use of npx in the CONTRIBUTING.md
snippet: change the command that currently runs "npx drizzle-kit push" to use
the project's pnpm toolchain, e.g., run "pnpm exec drizzle-kit push" so it
aligns with the packageManager and other docs; update the line referencing "npx
drizzle-kit push" accordingly.
Summary
.env.examplewith clear required/optional sections and uncommented GitHub App variablesTest plan
.env.examplerequired section lists all boot-time validated variables🤖 Generated with Claude Code
Note
Low Risk
Documentation-only updates that change onboarding instructions and
.envguidance; low risk aside from potential confusion if any prerequisites or required vars are misstated.Overview
Updates the README Quick Start to remove the “under 2 minutes” flow and instead point users to copying
apps/studio.giselles.ai/.env.exampleto.env.local, runningpnpm dev:studio.giselles.ai, and acknowledging required prerequisites (Node/pnpm/PostgreSQL/GitHub App/AI key).Adds a numbered, step-by-step local development setup section to
CONTRIBUTING.md, including prerequisites, required env vars, DB creation/migrations, and how to start the dev server.Reorganizes
apps/studio.giselles.ai/.env.exampleto clearly separate Required vs Optional variables and promotes GitHub App credentials into the required section; also adds a.continuityledger describing the doc changes and intent.Written by Cursor Bugbot for commit 18a92cb. This will update automatically on new commits. Configure here.
Summary by CodeRabbit