How do I connect Factory to GitHub/GitLab so it can open PRs and run our tests?

Connecting Factory to GitHub or GitLab is what turns Droids from “helpful in your editor” into “end-to-end teammates” that can propose real changes, open PRs, and wire into your CI tests. The good news: you don’t need to change your repos, workflows, or CI provider. You just give Factory permissioned access, map your repos, and point it at your existing test commands.

Below is a practical, system-focused walkthrough for teams asking: how do I connect Factory to GitHub/GitLab so it can open PRs and run our tests without bypassing our controls?

Quick answer: what you actually need to do

At a high level, connecting Factory to GitHub/GitLab so it can open PRs and run tests involves four steps:

Connect your VCS
- In Factory, add a GitHub App or GitLab Application with least-privilege repo and PR/MR scopes.
- Factory enforces strict permissions, so users only see repos they already have in GitHub/GitLab.
Authorize repos and projects
- Select which orgs/groups and repositories Droids can operate on.
- Factory mirrors your repo permissions and doesn’t pull in code outside those scopes.
Configure PR behavior
- Decide how Droids should propose changes: branches, PR titles, labels, reviewers, and target branches.
- Keep your normal review flow; Factory just becomes another contributor.
Wire up tests and CI
- Tell Factory how you run tests (e.g., npm test, pytest, mvn test) and how your GitHub Actions / GitLab CI pipelines are triggered.
- Droids generate edits, open a PR, and your existing CI runs as usual. Factory can read CI status, summarize failures, and iterate.

The rest of this guide walks through these steps in more detail for both GitHub and GitLab, with an emphasis on security, auditability, and keeping your current workflows intact.

How Factory talks to GitHub/GitLab

Factory’s design is straightforward: Droids don’t “own” your code; they operate within the same VCS and CI boundaries your engineers do.

Interface + vendor agnostic: GitHub and GitLab are just two of the surfaces Droids use, alongside VS Code/JetBrains/Vim, terminals, web, Slack/Teams, Jira/Linear, and CI.
Strict permissions enforcement:
- Factory only shows what a user can already access in GitHub/GitLab.
- Repo access is inherited from your VCS, not re-defined inside Factory.
Single-tenant isolation:
- Enterprise deployments run in a sandboxed, single-tenant environment with a dedicated VPC.
- TLS 1.2+ in transit, AES-256 at rest, and audit logs exportable to your SIEM.
No training on your code:
- Factory does not use your repositories as training data without prior written consent.

When Droids open PRs and run tests, they’re doing what an engineer would do with a local clone and CLI—just automated, scripted, and traceable.

Step 1: Connect Factory to GitHub

This is the recommended pattern for most teams using GitHub organizations.

1.1 Install the Factory GitHub App

Sign in to Factory with your SSO (SSO/SAML recommended for orgs).
Go to Settings → Integrations → GitHub.
Click Connect GitHub. This redirects you to GitHub’s App installation flow.
In GitHub, choose where to install the app:
- Organization level for team-wide use (recommended).
- User level for evaluation or personal repos.
Select Only select repositories or All repositories:
- For production orgs, “select repositories” gives tighter blast radius.
- You can always add more repos later as you expand Droid coverage.

Behind the scenes, the GitHub App grants scoped permissions so Factory can:

Read repositories and branches.
Create branches and commits.
Open and update pull requests.
Read PR status, checks, and comments.

Everything is scoped to the org/repos you just approved.

1.2 Verify permissions and repo scope

From Factory’s GitHub integration view:

Confirm the organizations and repos listed match what you intend Droids to see.
Ensure that “PRs / Code changes” or equivalent capability is enabled (depending on your plan/config).
For sensitive repos, double-check that access is either:
- Limited to specific teams via GitHub, or
- Excluded from the GitHub App selection.

Factory will enforce the same repo access each engineer already has in your GitHub org.

Step 2: Connect Factory to GitLab

If your team runs on GitLab (self-managed or GitLab.com), the flow is similar but uses GitLab Applications and access tokens.

2.1 Create a GitLab Application (admin step)

In GitLab (as an admin or group owner), go to:
- GitLab.com: Admin Area → Applications or group-level Settings → Applications.
- Self-managed GitLab: same path, depending on your version.
Create a new application named “Factory” (or similar).
Set the Redirect URI to the Factory GitLab integration callback (shown in Factory’s GitLab integration screen).
Assign scopes:
- api – needed for full repo, MR, and pipeline access.
- read_user – to associate GitLab users with Factory accounts.
- (Optional) narrower token if your internal policy prefers splitting responsibilities.

Save the application; GitLab will show a Client ID and Client Secret.

2.2 Connect GitLab from Factory

In Factory, go to Settings → Integrations → GitLab.
Enter the GitLab instance URL (e.g., https://gitlab.com or internal hostname).
Paste the Client ID and Client Secret you just created.
Click Connect and go through the OAuth consent screen.
Select the groups/projects Droids should be able to operate on.

Factory now has a scoped integration that can:

Read project code and branches.
Create branches, commits, and merge requests.
Read pipeline status and test results.

Step 3: Configure how Droids open PRs / MRs

Once GitHub/GitLab is wired in, define how Droids should propose changes so you maintain reviewability and traceability.

3.1 Branching and naming

Within Factory’s settings (or per-project config), you can define:

Default target branch:
- Usually main or develop.
- Droids create feature branches off this.
Branch naming convention:
- Example: factory/droid/<ticket-id>-short-summary
- This makes it trivial to trace work to tickets (e.g., Jira/Linear).
Force push behavior:
- Recommended: allow only safe, non-destructive updates or disable forced pushes entirely.

This standardizes the shape of Droid-created branches and makes them easy to audit.

3.2 PR/MR metadata: titles, labels, reviewers

You can also specify:

Title templates:
- Example: [Factory] {ticket-id}: {summary}
Default labels:
- ai-generated, factory, needs-review, etc.
- Helps your team quickly filter and monitor Droid contributions.
Reviewer assignment rules:
- Map repos or directories to owners.
- Ensure the right humans always review Droid PRs before merge.

Droids never bypass your code review process; they just create the artifacts.

Step 4: Let Factory run and interpret your tests

Factory doesn’t replace your CI; it uses your existing pipelines and test commands to validate changes.

There are two main paths:

Path A: Use your existing GitHub Actions / GitLab CI pipelines.
Path B: Let Droids run tests directly in a controlled environment (CLI/ephemeral).

Most teams do both: pipelines for gatekeeping, ad-hoc Droid test runs for faster inner loops.

4.1 Using existing GitHub Actions / GitLab CI pipelines

If your repo already has CI configured:

GitHub: .github/workflows/*.yml
GitLab: .gitlab-ci.yml

Then:

Droids create a branch and push commits.
CI pipeline triggers automatically (as usual).
Factory tracks pipeline status and surface it in the session:
- Green checks → Droids can finalize the plan, summarize the changes, and signal ready for human review.
- Red checks → Droids can inspect logs, summarize failure causes, and push targeted fixes.

No workflow file changes are required. Factory simply consumes the CI status and logs through the GitHub/GitLab APIs.

4.2 Defining test commands for local / Droid execution

For faster feedback loops (especially when debugging or migrating), configure test commands so Droids can run them in their environment:

In Factory project settings, define test profiles per repo or service:
- Backend: pytest, pytest -m "not slow", or go test ./...
- Frontend: npm test, pnpm test, or vitest run
- Monorepos: mapping from path → command.
Specify:
- Working directory (e.g., services/api, packages/web).
- Environment variables (non-production, sanitized).
- Timeouts and resource limits to prevent runaway jobs.

Example configuration (conceptual):

tests:
  - name: api-fast
    path: services/api
    command: pytest -q
    timeout_seconds: 600

  - name: web-unit
    path: apps/web
    command: npm test -- --runInBand
    timeout_seconds: 900

Droids can then:

Plan a change.
Apply edits.
Run the configured test command.
Parse failures, update the plan, and iterate until tests pass or a limit is hit.

This is where Factory’s agent design matters: explicit planning, environment discovery, and error recovery under timeouts are what make these loops actually complete instead of stalling on the first failure.

Step 5: End-to-end flow: from ticket to PR with tests

Once GitHub/GitLab and tests are integrated, a typical workflow looks like this:

Trigger from your backlog or editor
- From Jira/Linear: open a ticket, invoke a Droid, or rely on issue-triggered automation.
- From VS Code/JetBrains/Vim/terminal: describe the change and let the Droid gather context from code, docs, and past PRs.
Droid plans the work
- It enumerates files to touch, possible impacts, and the test suites to run.
- You review and refine the plan before execution.
Droid edits, tests, and iterates
- Applies code changes in your repo.
- Runs local or configured tests via CLI or triggers your CI.
- If failures occur, it inspects logs and retries with targeted fixes.
Droid opens a PR/MR in GitHub/GitLab
- Creates a branch with your naming convention.
- Pushes commits and opens a PR/MR with a structured summary: what changed, why, and which tests passed.
- Applies your labels and assigns reviewers based on repo rules.
Humans review and merge
- Your engineers review the PR exactly as they do today.
- Factory provides traceability from ticket → plan → edits → PR → CI status.
- Nothing merges without your existing checks and approvals.

This is how teams like Nav and Clari achieve higher velocity without sacrificing control: the Droids handle the unglamorous, repeatable work; engineers stay in the loop, reviewing and making decisions.

Security, compliance, and auditability

Connecting Factory to GitHub/GitLab doesn’t change your compliance posture; it extends it.

Key controls:

Strict permissions enforcement:
- Factory only displays repos and files that the signed-in user can access in GitHub/GitLab.
Audit logging:
- All Droid actions—file reads, edits, PR creations—are logged.
- Logs are exportable to your SIEM via standard formats and OpenTelemetry.
Isolated runtime:
- Single-tenant environment, dedicated VPC.
- No cross-tenant data mixing.
No unapproved training:
- Customer code and metadata are not used to train models without prior written consent.

You get AI agents that operate like disciplined teammates, not uncontrolled scripts.

Troubleshooting common issues

Droids can’t see a repo

Check that the GitHub App or GitLab Application includes that repo/group.
Confirm the user has access to the repo in GitHub/GitLab.
Sync or re-authorize the integration from Factory if access was recently granted.

PR creation fails

Verify branch protection rules; Droids don’t bypass protected branch policies.
Ensure the GitHub App/GitLab token has permission to create branches and PRs/MRs.
Check audit logs in Factory for an error message (e.g., permission denied, rate limit).

Tests aren’t running

If relying on CI:
- Confirm your workflow/yaml file is configured to run on pull_request or merge_request events from the Droid-created branches.
If using local/Droid runs:
- Validate the configured command works locally under the same path and environment.
- Increase timeouts for slower suites or split into multiple targeted profiles.

Final decision triggers

To decide you’re “done” setting up the integration, check for these signals:

A Droid can:
- Read a repo from GitHub/GitLab inside Factory.
- Make a small edit and push a branch.
- Open a PR/MR with your labels and reviewers attached.
- See CI results and summarize test outcomes.

Once this loop is verified on one service, you can safely scale to more repos, more teams, and more ambitious workflows—refactors, dependency upgrades, and incident response—without changing the way you review and ship code.

Next Step

Get Started