Git hosting

Source-control integration establishes which reviewed source may become an Opfield-managed artifact. The application owner owns repository and branch policy, the platform owner owns build and deployment settings, and the security owner approves provider permissions and secrets. Success means a specific commit can be traced through build evidence to an immutable artifact and a verified release.

Configure source integrations under Settings > Integrations. Supported providers are GitLab, GitHub, and generic Git. GitHub and generic Git connectors are available on every plan; the GitLab integration, including GitLab registry discovery, requires Personal or higher. GitLab connectors created on Community before 2.11 are kept but cannot be opened until a Personal or higher key is active. Git source builds require Business or Enterprise. For access to a remote operating system, use the separate SSH connections guide.

Use a dedicated machine or application identity with read-only repository access unless a workflow explicitly requires more. Restrict allowed repositories and hosts. Verify webhook authenticity, branch selection, commit resolution, and credential rotation.

Repository URLs must not contain embedded credentials. SSH host keys and HTTPS certificate validation must fail closed. Remove an integration only after dependent Docker, Compose, and Pages sources are identified and migrated.

Integration types

• GitLab: project and group discovery, repository operations, webhooks, variables, CI-related workflows, and optional registry discovery according to entitlement.
• GitHub: repository discovery and supported repository/Actions operations through the configured application or token path.
• Generic Git: bounded authenticated repository access when a first-class provider is not required.

GitLab

1. Use a dedicated GitLab user that is a member of only the required groups/projects. In GitLab, open the avatar menu, Edit profile > Access > Personal access tokens. Create a token (the UI may call this a legacy personal access token).
2. Set its name and expiry, then choose permissions from the table. Copy the secret immediately.
3. In Opfield’s GitLab integration, enter the instance origin, such as https://gitlab.example.com, without /api/v4, and the token. Select the allowed projects/groups rather than granting every discovered project.
4. Test the token, discover an allowed project, and verify repository and branch access. A GitLab deploy token is not a substitute for this API identity.

Workflow	GitLab token scopes
Discover projects and read API metadata	read_api
Read/clone repository source for builds	read_repository together with read_api for the first-class connector
Discover/pull private registry images	Add read_registry and the necessary project membership
Write files through the API, manage hooks/variables, or perform CI mutations	api; the user must also have the required project role
Push through Git over HTTPS	write_repository; this does not grant general API write access

For read-only builds start with read_api + read_repository, not api. The broad api scope is appropriate only when enabling the write workflows that need it. Token scopes cannot override protected-branch rules or missing project membership. User-specific GitLab authorization for interactive tools remains separate from the saved system token.

References: Create a GitLab personal access token, GitLab access-token scopes.

GitHub

Use Connect GitHub if the OAuth connection path is configured, and review the organization and repository access on GitHub’s consent screen. For the token path:

1. Open GitHub Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token (classic).
2. Set a dedicated name and expiration. Select repo for private repositories, or public_repo if only public repositories are needed. These are broad repository permissions, not read-only scopes: use an identity whose repository access is appropriately restricted.
3. Add optional permissions only for the corresponding workflow below. Generate and copy the token. Authorize it for organization SSO where required.
4. Add the token in Opfield’s GitHub integration, select the allowed repositories/organizations, and test repository discovery and the intended revision.

Additional use	Classic token scope
Read organization/team membership	read:org
Download packages from GitHub Packages	read:packages
Modify workflow files	workflow, in addition to repository access

Current compatibility limitation: Opfield detects GitHub token capabilities from classic OAuth scopes. A fine-grained PAT can authenticate at GitHub but still be reported without repository capabilities by this connector. Do not use it as a drop-in replacement for the recipe above. If the organization forbids classic PATs, use an approved configured OAuth path or resolve connector compatibility before connecting; do not weaken organization policy. No delete_repo or organization-administration scope is required just to build a saved repository.

References: Manage GitHub personal access tokens, Classic OAuth scope meanings.

Generic Git

1. At the Git server, create a dedicated credential that can clone the selected repositories. For example, a GitLab deploy token with read_repository can be used for Git-over-HTTPS access; it is not a first-class GitLab API token.
2. In Opfield, choose generic Git. Enter Git host URL, such as https://git.example.com, and the explicit Repositories, such as https://git.example.com/team/app.git.
3. Enter Username and Access token separately. For a deploy token, use the username issued with that token. Do not embed either value in repository URLs.
4. Run Test connection, then save. The connection test uses the first repository: also verify access to every other repository you allow before relying on it for a build.

This connector uses HTTPS credentials, not a private key imported from External SSH. It does not provide a universal Git-provider scope vocabulary or the full GitLab/GitHub API feature set. A successful clone does not imply permission to manage webhooks, variables, or CI through an API.

Configure safely

1. Create a dedicated provider or machine identity.
2. Grant read-only repository access unless a documented workflow needs writes.
3. Restrict organizations, groups, projects, and repositories using the connector’s supported selection mode.
4. Add the integration under Settings → Integrations.
5. Verify TLS or SSH host identity before saving credentials.
6. Test repository discovery and access to one allowed revision.
7. Test that an out-of-scope repository or host is denied.
8. Configure webhook authenticity and delivery only after the read path works.

Restrict repository access

The connector’s allowlist decides which repositories Opfield can reach at all. Git integration scopes decide which users, groups, API tokens, and OAuth grants may use them. Every Git scope except manage can be limited below the connector:

• GitLab: a group, which also covers its subgroups and every project under them, or a single project. Opfield reads a project’s parent groups from GitLab, so a project moved to another group follows its new group.
• GitHub: an owner, which covers every repository of that organization or user, or a single repository.
• Generic Git: the connector only.

Connector administration—settings, tokens, the allowlist, sync, test, and deletion—needs integrations:<provider>:manage on the connector or without a restriction; a group, owner, project, or repository grant never allows it.

To restrict a grant, open the scope’s restriction in the group editor, a user’s additional permissions, the API token form, or OAuth and MCP consent. Check a connector to cover all of its repositories, or open Add groups or projects… or Add owners or repositories… under the connector to search the provider and select targets. Grants store the provider’s numeric IDs, so renames and moves do not break them; a target that has since been deleted is shown as Unavailable and can still be removed.

With restricted grants:

• Connector, project, and repository lists, including the build source picker, show only what the grants cover. A project missing from a list is usually outside the grant rather than unsynchronized.
• Every repository operation checks the repository—files, branches, commits, pipelines and job logs, variables, webhooks, deploy tokens, registry settings, and sandbox clones—in the Console, the REST API, the AI Workspace, and MCP alike. A GitLab project outside the grant answers exactly like a project that is not synchronized: 404 GITLAB_PROJECT_NOT_FOUND, without its path, so project IDs cannot be probed. For GitHub and generic Git, where the caller already supplies the repository, a denial returns 403 CONNECTOR_SCOPE_DENIED with the required scope.
• Opfield uses the connector’s credential for a repository only when use covers that repository; otherwise it uses the user’s personal credential.
• Writes, secrets, sandbox clones, and the credential decision read a GitLab project’s groups or a GitHub repository’s owner fresh from the provider, so a transferred repository is judged by where it is now; plain reads may use a value cached for up to five minutes. Connector syncs and source webhook deliveries clear the cache.
• The search picker offers only targets inside the connector’s allowlist and is limited to 60 requests a minute per account; beyond that it returns 429 SCOPE_TARGET_RATE_LIMITED with Retry-After.
• API tokens and OAuth grants keep their own restrictions and are also checked against the owner’s current grants on every request. A token restricted to one project works while its owner holds the group that contains the project and stops working when the owner loses that access.

See Git integration restrictions for the exact qualifier format and the picker endpoints.

Source binding lifecycle

Who can build and view results?

Repository discovery and direct source operations use provider integration scopes. GitLab, GitHub, and generic Git share the same verbs: integrations:<provider>:view lists connectors, :manage configures, tests, and synchronizes them, :use uses the connector’s own credential, and :repo:read and :repo:write read or change repository content. Listing and reading GitLab’s synced projects needs integrations:gitlab:view. GitLab repo:read covers repository files, CI pipelines and job logs, and CI/CD variable keys, never values; changing variables needs repo:write, and reading GitHub Actions variable values needs integrations:github:repo:write. The built-in viewer and operator groups get integrations:gitlab:view only. See the scope reference. Each of these scopes can be limited to a connector, a GitLab group or project, or a GitHub owner or repository; see Restrict repository access.

Attaching or changing a source binding needs integrations:<provider>:use on the repository, next to the workload’s own permissions. use limited to that one project or repository is enough; repo:read and a personal provider credential are not needed, because builds use the connector credential. The built-in operator group can therefore see GitLab projects in the source picker but cannot save a source until it is given integrations:gitlab:use, preferably limited to the projects it builds. GitLab’s interactive tools in the AI Workspace ask for the user’s own GitLab authorization when use does not cover the project.

Starting a build from an already saved source is a resource action—docker:containers:manage for containers and Deployments, docker:compose:manage for Compose, and pages:deploy for Pages—and also checks the caller’s integrations:<provider>:use on the saved repository again, so revoking use stops manual rebuilds. repo:read is still not needed. Opfield also checks the saved connector, allowed repository, and source credentials.

Automatic builds from polling and webhooks depend on when the source was last saved:

• Sources saved before 2.11 keep building automatically exactly as before.
• Sources created or saved again since then build automatically only while the account that last saved them still holds integrations:<provider>:use on the repository and is active. Otherwise no build runs: the build history shows a cancelled build with SOURCE_OWNER_ACCESS_REVOKED and the message Build paused: <user> no longer has use on <repo>, recorded once per commit, and the source shows the same message as its polling or webhook error. Webhook deliveries are still accepted. Automatic builds resume when the account regains use, or when someone who holds it saves the source again.

Grant use to the teams that save sources, limited to their projects, before relying on automatic builds.

Build history and logs require view access to the target: docker:containers:view, docker:compose:view, or pages:view. Resource and inherited folder restrictions apply. Since 2.11, any action scope on the same target, such as docker:containers:manage, also grants view of it. Do not grant account-wide repository or node access to work around a missing target grant. See Permissions.

Saved source bindings

Docker workloads, Compose Projects, and Pages Projects create their own source bindings. A source binding records the integration, repository, revision selection, build configuration, automation policy, and source-scoped Build Secrets.

Removing an integration does not make dependent resources safe to rebuild. Inventory dependencies first, disable automatic actions, migrate each source binding, and verify the replacement revision and credentials.

Continue with Docker Git builds, Pages Git deployments, and Container registries. For other connector types, return to Integrations.

Troubleshooting

Separate authentication failure, allowlist denial, repository-not-found, revision resolution, webhook delivery, Build Worker admission, and entitlement failure. Preserve provider request IDs and Opfield task history without logging tokens, private keys, variables, or Build Secrets.

Production source workflow

Pin the production source to a reviewed branch policy and an exact resolved commit. A branch name is selection input; the commit digest is the immutable evidence of what was built. Confirm the application root, package manager, build script, artifact directory, runtime platform, and publish/deploy policy before enabling automatic actions. Keep Build Secrets separate from ordinary runtime Variables and expose only the values required during the build stage.

For Pages and managed Git builds, verify the complete chain: provider access, repository discovery, commit resolution, Build Worker admission, dependency fetch, artifact creation, vulnerability policy where enabled, immutable artifact identity, publication Tag or workload revision, and customer-facing health. A successful provider webhook or source clone is only the beginning of that chain.

Token expiry and rotation

Opfield records when GitLab connector tokens and users’ personal GitLab tokens expire and checks them daily.

• Alerts: Opfield alerts 30 and 7 days before a connector token, a personal GitLab token, or the authorization of an OAuth-connected integration expires, whenever the expiry is known. GitLab reports the expiry of its tokens; GitHub and generic Git tokens are covered when they are connected through OAuth.
• GitLab self-rotation: 14 days before expiry, Opfield rotates GitLab connector tokens and personal GitLab tokens that have the api or self_rotate scope. The new token keeps the previous lifetime, between 30 days and one year, and replaces the stored secret; the rotation is audited. Project and group access tokens cannot rotate themselves through this path and receive alerts only.
• Expired tokens: Opfield stops using a token once it has expired. An expired personal GitLab token fails with GIT_CREDENTIAL_EXPIRED (HTTP 428), so the user must authorize a new one; an expired GitLab connector token fails with CONNECTOR_TOKEN_EXPIRED (HTTP 409). Replacing an expired connector token does not require the old one.

Syncs, Docker sources, and Pages builds that depend on an expired token stop working until it is replaced, so treat the 30-day alert as the rotation deadline for tokens Opfield cannot rotate itself.

Rotation, migration, and removal

To rotate credentials, add the replacement to the provider and Opfield, verify discovery and one real build, then revoke the previous value. To migrate providers or repositories, freeze automatic deploys, record the last approved commit and artifact digest, configure the replacement source, compare the resolved tree, run a canary build, and explicitly move the production pointer only after verification.

Before deleting a connector, list every Docker, Compose, Pages, registry, webhook, and automation dependency. Disable triggers first. Existing immutable artifacts may continue running, but future builds, refreshes, or source-based recovery can fail after the connector disappears. Keep the last approved artifact and rollback instructions until the new source path has survived an operational cycle.

Security review

Review provider audit logs, installed application permissions, deploy keys, SSH host keys, webhook secrets, allowed organizations/repositories, and inactive bindings. Repository read access can expose proprietary source and configuration; write or workflow permissions can affect the software supply chain. Grant them only when the selected Opfield workflow requires them.

Source integration does not replace repository review, protected branches, dependency governance, or artifact approval. Opfield adds controlled discovery, build, deployment, scopes, and audit around those practices; it should consume the organization’s source policy rather than become an undocumented exception to it.