Self-Managed Source Control

Factory connects human users to a self-managed GitHub Enterprise Server or GitLab instance through an OAuth application that you register on your own server. An admin registers the app once, enters its credentials in Factory, and authorizes it; from then on your organization's repositories are available to human-run sessions like any other repository.

Repository credentials remain scoped to the identity running the session. Factory service accounts never inherit the organization OAuth authorization. GitHub Enterprise Server supports service accounts through a GitHub App installation, while GitLab Self-Hosted does not currently provide Git credentials to Factory service accounts.

Prerequisites#

Both OAuth integrations authorize once per organization for human users, so individual members never authorize the server themselves. Use a dedicated account in your source-control server as the connecting admin rather than a personal employee account. This keeps org-wide human access off one person's account lifecycle and lets you bound which repositories are exposed.

Credential behavior by identity#

If the required service-account credential is unavailable, Factory stops the operation instead of substituting the organization OAuth credential.

Connect GitHub Enterprise Server#

Factory requests the repo and read:org OAuth scopes and imports only organization-level repositories. Personal repositories owned by the authorizing account are never imported.

1. 1
   Register an OAuth app on your server

   In your GitHub Enterprise Server instance, go to Settings → Developer settings → OAuth Apps → New OAuth App. Register it under an organization you own rather than a personal account.

   • Application name: Factory Integration
   • Homepage URL: https://app.factory.ai
   • Authorization callback URL: https://api.factory.ai/api/integrations/redirect/github-es/callback

   If you run Factory on a dedicated control plane, substitute your own Factory API domain in the callback URL.

2. 2
   Copy the credentials

   Register the app, then copy the Client ID and generate a Client Secret. Store the secret in your secret manager before leaving the page; GitHub shows it once.

3. 3
   Enter the server details in Factory

   Open Settings → Integrations, choose GitHub Enterprise, and enter your server domain (for example https://github.your-company.com), Client ID, and Client Secret. Factory normalizes and validates the domain on save.

4. 4
   Authorize the app

   Start the connection. Factory redirects you to your instance to approve the OAuth app, then imports the repositories the authorizing account can reach. Enable the ones you want available in Factory from the repository list.

Service-account repository access#

A Factory service account can access a GitHub Enterprise Server repository only when a GitHub App is configured for your Factory organization and installed on that repository. The installation determines which repositories the service account can reach. If the selected repository is not covered, the session cannot clone, fetch, or push it.

Organization OAuth remains available to human users only. If you need service-account access and do not already have a GitHub App configured, contact support@factory.ai.

Connect GitLab Self-Hosted#

GitLab authorization for human-run sessions uses a dedicated instance user rather than the admin's own account, so repository access does not follow an individual's account lifecycle.

1. 1
   Create the instance application

   In your GitLab instance, go to Admin Area → Applications → Add new application.

   • Name: Factory Integration
   • Redirect URI: https://api.factory.ai/api/integrations/redirect/gitlab-sh/callback
   • Trusted: yes
   • Confidential: yes
   • Scopes: api, read_api, read_user, read_repository, write_repository, read_observability, write_observability

   Save the application and note the Application ID and Secret. Factory requests a conservative subset of these scopes at authorization time (api, read_user, read_repository, write_repository) so the flow works on older GitLab versions.

2. 2
   Create the Factory Droid user

   Go to Admin Area → Users → New User and create a user named Factory Droid with the username factory-droid and any email address you control. Then sign in as, or impersonate, that user before continuing.

3. 3
   Enter the application details in Factory

   Open Settings → Integrations, click Connect next to GitLab, and toggle Self-Hosted. Enter your instance domain (use the externally reachable domain if you run split internal and external DNS), the Application ID, and the Secret, then save.

4. 4
   Authorize as the Factory Droid user

   Click Manage GitLab Self-Hosted Permissions. A pop-up authorizes the integration against your instance. You must still be signed in as, or impersonating, the factory-droid user at this point, or the authorization is recorded against the wrong account. Your repositories then appear in the repository list, where you enable the ones Factory should use.

Token and credential lifecycle#

Because the OAuth authorization is org-wide for human users, deleting or deactivating the connecting account on your server disconnects every human user at once. This is the main reason to authorize with a dedicated source-control account. That account is separate from a Factory service account and does not give Factory service accounts access to the OAuth credential.

Troubleshooting#

Integration configuration and authorization changes are recorded as integration_change events in the audit log.