Skip to content

setup.md

Latest commit

 

History

History
177 lines (144 loc) · 47.3 KB

setup.md

File metadata and controls

177 lines (144 loc) · 47.3 KB
Raw

Setup Guide

Manual Setup

Requirements: You must be a repository admin to complete these steps.

  1. Install the Droid GitHub app to your repository: https://github.com/apps/factory-droid
  2. Add FACTORY_API_KEY to your repository secrets. You can generate an API key at https://app.factory.ai/settings/api-keys
  3. Copy the workflow files from .github/workflows/droid.yml and .github/workflows/droid-review.yml into your repository's .github/workflows/

Security Best Practices

⚠️ IMPORTANT: Never commit API keys directly to your repository! Always use GitHub Actions secrets.

To securely use your Factory API key:

  1. Add your API key as a repository secret:

    • Go to your repository's Settings
    • Navigate to "Secrets and variables" → "Actions"
    • Click "New repository secret"
    • Name it FACTORY_API_KEY
    • Paste your API key as the value

  2. Reference the secret in your workflow:

    factory_api_key: ${{ secrets.FACTORY_API_KEY }}

Never do this:

# ❌ WRONG - Exposes your API key
factory_api_key: "fk-..."

Always do this:

# ✅ CORRECT - Uses GitHub secrets
factory_api_key: ${{ secrets.FACTORY_API_KEY }}

This applies to all sensitive values including API keys, access tokens, and credentials. We also recommend that you always use short-lived tokens when possible

Setting Up GitHub Secrets

  1. Go to your repository's Settings
  2. Click on "Secrets and variables" → "Actions"
  3. Click "New repository secret"
  4. For authentication, choose one:
    • API Key: Name: FACTORY_API_KEY, Value: Your Factory API key (starting with fk-)
  5. Click "Add secret"

Best Practices for Authentication

  1. ✅ Always use ${{ secrets.FACTORY_API_KEY }} in workflows
  2. ✅ Never commit API keys or tokens to version control
  3. ✅ Regularly rotate your API keys and tokens
  4. ✅ Use environment secrets for organization-wide access
  5. ❌ Never share API keys or tokens in pull requests or issues
  6. ❌ Avoid logging workflow variables that might contain keys

Review UX v2 permissions and defaults

Use this permission block for a mention workflow that supports review and fix:

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write
  actions: read
  checks: write
  • contents: write is needed for fix/report publishing. Use contents: read and fix_mode: off for review-only workflows.
  • pull-requests: write writes summary comments, reviews, replies, and thread resolutions.
  • checks: write belongs to the caller workflow token. It does not broaden the Factory App token. Missing check permission warns once and degrades without failing the review.
  • id-token: write is required for default Factory App authentication. A supplied github_token must have its own necessary permissions.
  • Keep checkout persist-credentials: false. A model step does not need publishing credentials. Token withholding is hygiene, not an OS sandbox; code and tools still run as the job user.
  • Require Droid Review for code review and Droid Security Review for standalone security review if you want the corresponding priority or security thresholds to block merging. Droid never approves or requests changes.

The default surface is one sticky comment with a verdict and linked findings, colored image severity labels, collapsed safe agent prompts, and a clean-review message, without a Review details dropdown. Lifecycle reactions are eyes, hooray, and confused, never thumbs feedback. With review_summary: off, lifecycle reactions are skipped when no current owned summary session can establish safe run ownership. Reviews are incremental by default; the validator confirms fixes before automatic thread resolution. Generated/lock files are excluded from review.

See the effective-default table and base configuration example. Configuration precedence is built-in defaults, immutable base-branch .factory/review.yaml, then explicit nonempty workflow inputs. Explicit false and 0 override the file. An empty config-enabled input inherits; off clears a priority gate and [] clears a list. Labels are not a supported trigger; label_trigger is retained only as an unsupported legacy input.

Complete GitHub action input reference

This table reflects the root action.yml. "" means inherit for config-enabled review settings, or unset for standalone options. The README lists effective review defaults. GitLab's separate component reference is in GitLab setup; do not pass GitHub-only inputs to that component.

Input Manifest default Description
trigger_phrase @droid The trigger phrase to look for in comments or issue body
assignee_trigger Unset The assignee username that triggers the action (e.g. @droid)
label_trigger "" (inherit or unset) Unsupported legacy input. Label-triggered execution is disabled; use automatic_review or explicit mentions.
allowed_bots "" (inherit or unset) Comma-separated list of allowed bot usernames, or '*' to allow all bots. Empty string (default) allows no bots.
allowed_non_write_users "" (inherit or unset) Comma-separated list of usernames to allow without write permissions, or '*' to allow all users. Only works when github_token input is provided. WARNING: Use with extreme caution - this bypasses security checks and should only be used for workflows with very limited permissions (e.g., issue labeling).
settings "" (inherit or unset) Droid Exec settings as JSON string or path to settings JSON file
factory_api_key Required Factory API key (required for Droid Exec runtime)
github_token Installed App token GitHub token with repo and pull request permissions (optional if using GitHub App)
droid_args "" (inherit or unset) Additional arguments to pass directly to Droid CLI
additional_permissions "" (inherit or unset) Additional GitHub permissions to request (e.g., 'actions: read')
use_sticky_comment false Use just one comment to deliver issue/PR comments
track_progress false Force tag mode with tracking comments for pull_request and issue events. Only applicable to pull_request (opened, synchronize, ready_for_review, reopened) and issue (opened, edited, labeled, assigned) events.
automatic_review "" (inherit or unset) Run automatic code review without a mention. Effective default false; empty inherits base config.
automatic_security_review "" (inherit or unset) Run automatic security review. Effective default inherits automatic_review; explicit false opts out.
security_model "" (inherit or unset) Advanced. Leave empty to use the review_depth preset (recommended). Falls back to review_model. If set, use a provider tier alias such as 'openai-latest-premium' or 'anthropic-latest-balanced'. Only applies to security review flows.
security_severity_threshold "" (inherit or unset) Minimum security severity: critical, high, medium (effective default), or low. Empty inherits base config.
security_block_on_critical "" (inherit or unset) Fail the check run for critical security findings, never request changes. Effective default true.
security_block_on_high "" (inherit or unset) Fail the check run for high security findings, never request changes. Effective default false.
security_notify_team "" (inherit or unset) GitHub team to @mention on critical findings (e.g., '@org/security-team').
security_scan_schedule false Enable scheduled security scans. Set to 'true' for schedule events to trigger full repository scans.
security_scan_days 7 Number of days of commits to scan for scheduled security scans. Only applies when security_scan_schedule is enabled.
review_depth "" (inherit or unset) Review depth: deep (effective default) or shallow. Empty inherits base-branch config; unknown values warn and use deep.
review_model "" (inherit or unset) Advanced. Leave empty to use the review_depth preset (recommended). If set, use a provider tier alias such as 'openai-latest-premium' or 'anthropic-latest-balanced'; overrides the preset model.
reasoning_effort "" (inherit or unset) Advanced. Leave empty to use the review_depth preset (recommended). Overrides the preset reasoning effort for review flows.
include_suggestions true Include code suggestion blocks in review comments when the fix is high-confidence. Set to 'false' to disable suggestions.
review_candidates_path ${{ runner.temp }}/droid-prompts/review_candidates.json Path to write review candidates JSON (pass 1 of the two-pass review).
review_validated_path ${{ runner.temp }}/droid-prompts/review_validated.json Path to write review validated JSON (pass 2 of the two-pass review).
review_candidates_max_turns 100 Maximum agent turns for review candidate generation (pass 1). Empty disables the cap.
review_validator_max_turns 40 Maximum agent turns for review validation (pass 2). Empty disables the cap.
fill_model "" (inherit or unset) Advanced. Leave empty to use the default model (recommended). If set, use a provider tier alias such as 'openai-latest-premium' or 'anthropic-latest-balanced'. Only applies to fill flows.
experimental_allowed_domains "" (inherit or unset) Restrict network access to these domains only (newline-separated). If not set, no restrictions are applied. Provider domains are auto-detected.
path_to_droid_executable "" (inherit or unset) Optional path to a custom Droid CLI executable. If provided, skips automatic installation and uses this executable instead. WARNING: Using an older version may cause problems if the action begins taking advantage of new Droid Exec features. Review runs pass a JSON --tag (supported since the June 2026 CLI); an older CLI stores the JSON as a literal tag name and the session is not classified as a code review. This input is typically not needed unless you're debugging something specific or have unique needs in your environment.
path_to_bun_executable "" (inherit or unset) Optional path to a custom Bun executable. If provided, skips automatic Bun installation and uses this executable instead. WARNING: Using an incompatible version may cause problems if the action requires specific Bun features. This input is typically not needed unless you're debugging something specific or have unique needs in your environment.
show_full_output false Show full JSON output from Droid Exec. WARNING: This outputs ALL Droid messages including tool execution results which may contain secrets, API keys, or other sensitive information. These logs are publicly visible in GitHub Actions. Only enable for debugging in non-sensitive environments.
upload_debug_artifacts false Upload a droid-review-debug-<run_id> workflow artifact with Droid's logs, session transcripts and review prompts, for troubleshooting. Known credentials are redacted and Droid's MCP configuration is never included, but the files still contain pull request content and anything Droid printed. Anyone who can read the repository's Actions runs can download the artifact; on a public repository that is any signed-in GitHub user.
ci_steward false Enable CI Steward mode for workflow_run events.
auto_fix false Allow CI Steward to commit fixes directly to the pull request branch.
retry_mode smart CI Steward retry policy: off, always, or smart.
max_retries 1 Maximum reruns for each failed job and commit.
max_fix_attempts 2 Maximum consecutive fix commits from CI Steward.
max_runs_per_pr 10 Lifetime maximum CI Steward invocations for a pull request.
steward_model "" (inherit or unset) Model used by CI Steward.
instructions "" (inherit or unset) Additional instructions for CI Steward.
config_path .github/droid-ci.yml Repository CI Steward configuration path.
review_summary "" (inherit or unset) Summary location: comment (effective default), description, or off. Empty inherits base-branch config.
review_summary_sections "" (inherit or unset) Visible sections. Effective default: verdict,findings,changes,details; also diagram,risk,effort. Empty inherits base config; [] disables optional sections.
review_badges "" (inherit or unset) Severity badges: image (effective default), emoji, or text. Empty inherits base config.
review_reactions "" (inherit or unset) Lifecycle reactions: eyes while running, hooray when clean, confused on failure. Effective default true; no thumbs-up/down.
review_check_run "" (inherit or unset) Create the Droid Review check run with the caller token. Effective default true; missing checks write warns once.
fail_on_severity "" (inherit or unset) Fail the check at or above P0, P1, or P2. Effective default empty (no priority gate); off explicitly disables a base-config gate.
review_incremental "" (inherit or unset) Review only new commits after the first run. Effective default true; empty inherits base config.
review_auto_resolve "" (inherit or unset) Resolve verified fixed Droid threads. Effective default true; empty inherits base config.
review_max_auto_runs "" (inherit or unset) Auto-pause after this many automatic reviews. Effective default 0 (unlimited); explicit 0 overrides base config.
show_dropped_findings "" (inherit or unset) List validation-dropped candidates and reasons. Effective default false; empty inherits base config.
include_agent_prompts "" (inherit or unset) Include untrusted-data-safe AI agent prompts. Effective default true; empty inherits base config.
fix_mode "" (inherit or unset) Droid fix publishing mode: commit (effective default), pr, or off. Commit falls back to an authorized stacked PR for protected branches; inaccessible forks are refused.
review_diagram "" (inherit or unset) What changed diagram: auto (effective default) or off. Empty inherits base config.
review_severity_threshold "" (inherit or unset) Minimum reported finding priority: P0, P1, or P2 (effective default). Empty inherits base config.
review_ignore_paths "" (inherit or unset) Comma/newline-separated ignored globs. Effective default generated files, dist/build/coverage and lock files; [] disables ignores. Empty inherits base config.
review_auto_triggers "" (inherit or unset) Automatic PR event actions. Effective default opened,reopened,synchronize,ready_for_review. [] disables automatic event triggers.
review_drafts "" (inherit or unset) Review draft PRs automatically. Effective default false; manual review commands still run.
review_effort "" (inherit or unset) Show an evidence-based effort estimate. Effective default false; empty inherits base config.
review_category_chips "" (inherit or unset) Show finding category chips. Effective default false; empty inherits base config.
review_suggest_reviewers "" (inherit or unset) Suggest CODEOWNERS reviewers, never assign them. Effective default false.
review_pre_merge_checks "" (inherit or unset) Opt-in checks: title,description,linked_issue. Effective default none; [] explicitly clears base checks.

Preview and offline validation

include_agent_prompts: false disables both the Fix in Factory button and agent-copy prompts. Omitting findings from review_summary_sections also hides the summary button and copy prompt. Suggested reviewers and pre-merge checks follow their own opt-in settings, independently of the selected summary sections.

The examples are generated from structured fixture JSON, not posted to a live PR:

bun run scripts/preview-review.ts docs/review-ux-preview.md
bun test
bun run typecheck
bun run format:check

Rendered examples include findings, clean, in-progress, failed, skipped and re-review summaries; inline comments; stale review bodies; check summaries; and full-security report indexes. The preview validates balanced details/fences, nonempty sections, badges, count pluralization, and marker roundtrips.

No live PR/MR test is required or performed by this workflow change. API tests mock the provider boundary. Native text severity badges do not request external images, but the Fix in Factory button loads a static shields.io image unless disabled with include_agent_prompts: false or the findings section. Its /new?prompt= link prefills an editable prompt in the browser without sending it; the desktop app can auto-send the same route. Always inspect the prompt before sending. Explicit image badges and GitLab instance-specific Markdown sanitization still depend on the host.