Skip to main content
The Factory Droid GitHub Action enables automated code review and PR assistance directly within your GitHub workflows. This page explains the security architecture, data flows, and controls that govern how the integration operates.

​
Overview

The Droid GitHub Action (Factory-AI/droid-action) runs entirely inside GitHub Actions using your own runners. It does not require a separate hosted service or persistent connection to Factory infrastructure beyond standard API authentication.

Runs in your environment

The action executes on GitHub‑hosted or self‑hosted runners you control. No external compute resources are provisioned.

No persistent code storage

Code is checked out transiently for the workflow run and discarded afterward. Factory does not store your source code.

Scoped permissions

The action requests only the GitHub permissions it needs and tokens are automatically revoked after each run.

Standard Factory authentication

Uses your Factory API key, subject to your org’s existing model allowlists, rate limits, and policies.

​
Architecture and data flows

When a workflow runs, the following sequence occurs:
  1. Trigger detection – The action detects @droid mentions in PR comments, descriptions, or review comments.
  2. Permission verification – Before executing, the action verifies the triggering user has write access to the repository.
  3. Context gathering – Droid collects PR metadata, changed files, and existing comments from the checked‑out repository.
  4. Droid Exec – The CLI runs with GitHub MCP tools pre‑registered, allowing it to interact with the PR via GitHub APIs.
  5. LLM requests – Prompts are sent to your configured model providers through Factory’s standard routing.
  6. Results – Droid posts inline comments or updates the PR description directly via GitHub APIs.
  7. Token revocation – GitHub App tokens are automatically revoked at the end of the workflow.

​
Data boundaries

Data typeWhere it flowsRetention
Source codeGitHub runner (transient checkout)Discarded after workflow
PR metadataGitHub APIsGitHub’s retention policies
Prompts and contextConfigured LLM providersPer your model provider agreements
Workflow logsGitHub ActionsYour repository’s log retention settings
Debug artifactsGitHub Actions artifacts7 days (configurable)

​
Authentication and authorization

​
Factory API key

The action requires a Factory API key (FACTORY_API_KEY) stored as a GitHub secret. This key:
  • Authenticates Droid Exec sessions with Factory’s API.
  • Is subject to your org’s model allowlists, rate limits, and policies.
  • Should be rotated regularly following your organization’s key management practices.
Never commit API keys directly to your repository. Always use GitHub Actions secrets.

​
GitHub App tokens

When using the Factory Droid GitHub App:
  • The app requests an installation token scoped to the specific repository.
  • Tokens are short‑lived and automatically revoked after the workflow completes.
  • The app only requests permissions necessary for its operation (contents, pull requests, issues).
If you prefer not to use the GitHub App, you can provide a custom github_token input with appropriate permissions.

​
User permission verification

Before executing any @droid command, the action verifies:
  1. The triggering user has write access to the repository.
  2. The user is not a bot (unless explicitly allowed via allowed_bots input).
  3. The comment or trigger matches the expected format.
This prevents unauthorized users from invoking Droid.

​
Security controls

​
Permission scoping

The action requests only the GitHub permissions it needs: 
permissions:
  contents: write # Read code, write for fixes
  pull-requests: write # Comment on and update PRs
  issues: write # Comment on issues
  id-token: write # OIDC token for secure auth
  actions: read # Read workflow run metadata
You can further restrict permissions in your workflow file based on your security requirements.

​
Bot and user filtering

Control who can trigger the action:
InputPurpose
allowed_botsComma‑separated list of bot usernames allowed to trigger, or * for all. Default: none.
allowed_non_write_usersUsernames to allow without write permissions. Use with extreme caution.

​
Network restrictions (experimental)

For enhanced security, you can restrict network access during Droid execution: 
- uses: Factory-AI/droid-action@v1
  with:
    factory_api_key: ${{ secrets.FACTORY_API_KEY }}
    experimental_allowed_domains: |
      api.factory.ai
      api.anthropic.com
      api.openai.com
This limits outbound connections to only the specified domains.

​
Secrets protection

The action follows security best practices for secrets handling:
  • API keys are passed via environment variables from GitHub secrets.
  • The show_full_output option is disabled by default to prevent accidental exposure of sensitive data in logs.
  • Debug artifacts are retained for only 7 days by default.
Enabling show_full_output may expose sensitive information in publicly visible workflow logs. Only enable for debugging in non‑sensitive environments.

​
Audit and monitoring

​
Workflow logs

All Droid activity is logged in GitHub Actions workflow runs, providing:
  • Timestamps for all operations.
  • Command inputs and outputs (unless containing sensitive data).
  • Success/failure status for each step.
  • Links to any comments or changes made.

​
Debug artifacts

The action uploads debug artifacts including:
  • Droid session logs.
  • Console output.
  • Session metadata.
These artifacts are retained for 7 days by default and can be used for troubleshooting or audit purposes.

​
Integration with Factory telemetry

If your organization uses Factory’s OTEL telemetry, Droid Exec sessions from GitHub Actions are included in your telemetry data, providing:
  • Session metrics tagged with repository and workflow context.
  • LLM usage and cost attribution.
  • Tool invocation tracking.
See Compliance, Audit & Monitoring for details on Factory’s telemetry capabilities.

​
Deployment recommendations

  1. Use repository secrets – Store FACTORY_API_KEY as a repository or organization secret.
  2. Review workflow permissions – Ensure the workflow file requests only necessary permissions.
  3. Restrict bot access – Keep allowed_bots empty unless you have a specific need.
  4. Enable branch protection – Require PR reviews before merging Droid‑assisted changes.
  5. Monitor workflow runs – Review Droid activity in your GitHub Actions logs regularly.
  6. Consider network restrictions – Use experimental_allowed_domains to limit network access.
  • Self‑hosted runners – Run the action on self‑hosted runners in your controlled environment.
  • Model allowlists – Configure Factory org policies to restrict which models Droid can use.
  • Audit retention – Adjust artifact retention periods to meet your compliance requirements.
  • Integrate with SIEM – Export GitHub Actions logs and Factory telemetry to your security monitoring tools.

​
Comparison with other deployment patterns

AspectGitHub ActionCLI on developer machineDroid Exec in CI
Execution environmentGitHub runnersLocal workstationYour CI runners
Code accessTransient checkoutFull local accessTransient checkout
AuthenticationFactory API keyFactory API keyFactory API key
TriggerPR events, commentsManual invocationCI pipeline events
Audit trailGitHub Actions logsLocal + Factory telemetryCI logs + Factory telemetry
All deployment patterns use the same underlying Droid Exec runtime and are subject to the same Factory org policies.