Git hosting

Source-control integration establishes which reviewed source may become a Gateway-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 according to connector and plan availability. 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 Gateway’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 Gateway’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: Gateway 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 Gateway, 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.

Source binding lifecycle

Who can build and view results?

Repository discovery and direct source operations use provider integration scopes. Attaching or changing a source binding must pass the applicable connector and repository checks. GitLab’s interactive source tools may also require the user’s own GitLab authorization unless system credentials are explicitly permitted.

Starting a build from an already saved Docker source is a resource action: docker:containers:manage for containers/deployments or docker:compose:manage for Compose. It does not require giving the operator separate integrations:gitlab:repo:read access just to run that saved build. Gateway still checks the saved connector, allowed repository, and source credentials. Pages uses pages:deploy for deployment actions.

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; manage permission alone is not a substitute for view. 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 Gateway 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.

Rotation, migration, and removal

To rotate credentials, add the replacement to the provider and Gateway, 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 Gateway workflow requires them.

Source integration does not replace repository review, protected branches, dependency governance, or artifact approval. Gateway 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.