GitHub Actions

Run Droid Exec from GitHub Actions for pull request reviews, scheduled maintenance, and security checks.

Use Droid Exec in GitHub Actions when you want Factory to run a one-shot task from CI: review a pull request, refresh generated docs, scan for security risks, or run any repeatable repository workflow.

Use the base scaffold once, then swap in the task-specific snippet that matches your workflow.

Prerequisites

Before adding Droid Exec to a workflow:

1. Generate a Factory API key from Factory Settings → API Keys.
2. Add it to your repository secrets as FACTORY_API_KEY under Settings → Secrets and variables → Actions.
3. Decide the minimum autonomy level the workflow needs. Most CI workflows should start with --auto low and only use broader permissions when the task truly requires them.

Never hardcode a Factory API key in a workflow file. Always reference ${{ secrets.FACTORY_API_KEY }}.

Base workflow scaffold

Every GitHub Actions workflow using Droid Exec follows the same shape: check out the repository, install the Droid CLI, pass FACTORY_API_KEY, and run droid exec with a scoped prompt.

name: Droid Task
on: pull_request

jobs:
  droid-task:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Setup Droid CLI
        run: |
          curl -fsSL https://app.factory.ai/cli | sh
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Run Droid Exec
        env:
          FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
        run: |
          droid exec --auto low "Summarize the key risks in this change. Do not modify files."

Raise permissions and the autonomy level only for workflows that need to write files, create pull requests, or open issues.

Task snippets

Keep the checkout and Setup Droid CLI steps from the scaffold, then replace the final Run Droid Exec step with the relevant snippet. Also update the workflow trigger and job permissions as shown in the customization table below.

PR review and fix

- name: Review and fix
  env:
    FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
  run: |
    git diff origin/${{ github.base_ref }}...HEAD > /tmp/pr.diff

    droid exec --auto low \
      "Review /tmp/pr.diff and fix only high-confidence bugs, typos, missing error handling, or broken tests introduced by this pull request. Do not make stylistic rewrites."

    droid exec --auto low \
      "Write /tmp/review.md with: summary of fixes made, remaining issues for humans, security or performance concerns, and test recommendations."

- name: Commit fixes
  run: |
    if [ -n "$(git status --porcelain)" ]; then
      git config user.name "github-actions[bot]"
      git config user.email "github-actions[bot]@users.noreply.github.com"
      git add -A
      git commit -m "fix: apply Droid review fixes"
      git push
    fi

- name: Comment on pull request
  if: always()
  uses: actions/github-script@v7
  with:
    script: |
      const fs = require('fs');
      const body = fs.existsSync('/tmp/review.md')
        ? fs.readFileSync('/tmp/review.md', 'utf8')
        : 'Droid review completed.';
      await github.rest.issues.createComment({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number,
        body,
      });

What to customize

Workflow	Trigger	Job permissions	Notes
PR review and fix	pull_request with opened, synchronize, reopened, ready_for_review	contents: write, pull-requests: write	Use only for trusted repositories where the Actions token may push to the source branch.
Scheduled maintenance	schedule plus workflow_dispatch	contents: write, pull-requests: write	Good for recurring docs, test, or lightweight maintenance PRs.
Security scan	schedule plus workflow_dispatch	contents: read, issues: write	Creates an issue when Droid writes actionable findings.

For a maintained review workflow with inline comments, review depth, security review, and scheduled scans, use the Automated Code Review guide.

Prompt design for CI

CI prompts should be durable enough to run without a human in the loop.

• Name the input: tell Droid whether to inspect a diff file, changed files, the whole repository, or a prompt file.
• Constrain writes: say whether Droid may edit files, create reports, open issues, or only print findings.
• Define success: request a specific artifact such as review.md, maintenance-summary.md, or security-report.md.
• Exclude low-value work: tell Droid not to make stylistic rewrites unless the workflow exists for cleanup.
• Start read-only: use no --auto flag for analysis-only tasks; use --auto low when the workflow needs safe file operations.

See also

• Droid Exec overview
• Automated Code Review
• CLI reference