Git connections
Git connections are reusable, administrator-configured sets of access parameters for Git repositories. The project version export and import dialogs use them, so users pick a ready connection from a list instead of entering the repository URL and credentials every time. Git connections are managed in Settings → Integrations, on the Git connections tab.
Purpose and scope
A Git connection stores everything needed to reach a Git repository: the repository URL, the path inside it, the default branch, and the credentials. Version export and import (described on the corresponding page of the Projects section) then only ask the user to select a connection.
Key properties:
- A connection belongs to the company of the user who created it. Users with the Administrator and Super administrator roles see and manage only their own company's connections; the connections of other companies are neither shown nor offered in the version export and import dialogs
- Connections are not tied to a single project or version — they exist at the company level and are available in all of the company's projects
- Creation, editing, deletion, testing, and use of Git connections in export and import are recorded in the System Journal
Access permissions
| Role | Manage Git connections (view, create, edit, delete) | Select a connection in the version export/import dialogs |
|---|---|---|
| Super administrator | Yes (own company's connections) | Yes |
| Administrator | Yes (own company's connections) | Yes |
| Project manager, Developer | No | Yes |
| Analyst, Viewer | No | In the export dialog only — these roles cannot import versions |
The Integrations page is available only to administrators; users with other roles cannot open it, but they can use the existing connections in the version transfer dialogs.
Connections list
The Git connections tab shows the company's connections as a table:
| Column | Description |
|---|---|
| Name | Name set by the user |
| Platform | The Git platform of the repository |
| Repository URL | Address of the repository |
| Path in repository | The directory inside the repository that versions are exported into |
| Status | Available (green indicator) or Unavailable (red indicator) |
| Actions | Edit, test connection, and delete buttons |
Above the table there is an Add Git connection button. The table supports sorting and search by name, platform, repository URL, path in repository, and status: platform and status are filtered by selecting a value from a list, the other columns by case-insensitive substring search. The list is paginated, 20 records per page by default.
Connection status
| Status | Meaning |
|---|---|
| Available (green) | The last test was successful: the repository is reachable, the credentials were accepted, the default branch exists, and write access is confirmed |
| Unavailable (red) | The last test failed, or no test has been performed yet |
The status is updated only by the connection test — either run manually or performed when the connection is saved.
Creating a connection
- Click Add Git connection above the list
- Fill in the connection parameters (see the table below) and the credentials of the selected authentication method
- Optionally click Test connection to check the current form values without saving
- Save the connection. On saving, the connection is tested automatically: it is created only when the test succeeds. If the test fails, the dialog stays open and the specific reason is shown
| Parameter | Required | Description |
|---|---|---|
| Name | Yes | Connection name, 1–255 characters |
| Platform | Yes | One of: GitHub, GitHub Enterprise, GitLab (including self-hosted), Bitbucket, Azure DevOps, Generic Git (any Git server). Cannot be changed after creation |
| Repository URL | Yes | Address of the repository. Spaces and Cyrillic characters are not allowed; the address must match the selected platform and authentication method (https for token and password methods, SSH for the SSH key method). A missing .git suffix and a trailing slash are allowed |
| Path in repository | Yes | The directory inside the repository used for version transfer, up to 500 characters. Leading and trailing slashes are stripped |
| Default branch | Yes | The branch used by default, main unless changed. After a successful connection test, the field offers the actual list of the repository's branches |
| Authentication method | Yes | One of the methods described below |
Authentication methods
| Method | Credential fields | Notes |
|---|---|---|
| Personal access token | Token | The token must grant write access to the repository. Requires an https repository URL |
| Username / password | Username, Password | Requires an https repository URL |
| SSH key | Private key, Passphrase (optional), Public key (read-only) | Requires an SSH repository URL. The public key is extracted from the private key on save and shown in the form — add it to the repository on the platform side |
| OAuth2 | OAuth client ID, OAuth client secret, authorization status, Sign in with {platform} button | Available for GitHub, GitHub Enterprise, and GitLab only. If a platform without OAuth2 support is selected, the method falls back to Personal access token |
OAuth2 sign-in. The Sign in with {platform} button opens a popup with the platform's authorization page. After the user confirms access, the authorization result is passed back to the dialog and the connection can be saved. The authorization is short-lived: if it expires before saving, the message "The OAuth authorization expired — sign in again before saving" is shown and the sign-in must be repeated. For self-hosted GitLab and GitHub Enterprise, the platform address is derived from the repository URL.
All credentials — tokens, passwords, SSH keys, passphrases, and OAuth secrets — are stored encrypted and are never displayed back after saving.
Testing a connection
A connection can be tested in two ways:
- With the Test connection button in the creation or editing dialog — the current form values are tested; nothing is saved and the stored status does not change. For an existing connection, an untouched secret field is substituted with the stored credentials
- With the Test connection action in the list row — the stored credentials are used, and the resulting status is saved in the connection
The test checks, in order:
- that the repository is reachable at the specified URL, and requests its list of branches (a successful response fills the Default branch suggestions)
- that the credentials are accepted by the platform
- that the default branch exists (skipped for an empty repository — an empty repository is a valid export target and is initialized on the first export)
- that the credentials allow pushing to the repository (checked without writing anything to it)
The result is shown as a success or failure notification. Failure messages point at the specific problem:
| Message | Cause and recovery |
|---|---|
| "Git repository rejected the credentials" | The token, password, key, or OAuth grant was not accepted — update the credentials |
| "Git repository is unreachable" | The host does not respond or the connection timed out — verify the URL and check the network |
| "The repository is hosted on an address that outbound connections are not allowed to reach" | Outbound connections to the repository host are not permitted by the server configuration — contact your administrator |
| "The default branch does not exist in the repository" | The specified branch is absent from a non-empty repository — pick an existing branch |
| "The credentials do not allow pushing to the repository" | The credentials are read-only — update the token scopes or key permissions |
| "A token is required to test the connection" | No credentials were entered and none are stored |
| "The selected authentication method is missing its credentials" | The fields required by the method were not filled in |
| "The OAuth authorization expired — sign in again before saving" | Repeat the OAuth sign-in |
| "Failed to test the Git connection" | Any other error while contacting the repository |
Error messages never contain credentials: tokens, keys, and passphrases are stripped before display.
Editing a connection
- A stored secret is shown as placeholder characters (
••••••••••••) and cannot be edited until the pencil button next to the field is clicked. Leaving the secret field empty on save keeps the stored value - Changing the Authentication method invalidates the stored credentials — the credentials of the new method must be entered again
- The Platform cannot be changed — to switch platforms, create a new connection
- For OAuth2 connections, the client ID and client secret can be changed and saved without signing in again; the Re-authenticate button performs a new OAuth sign-in and replaces the stored authorization
Unlike creation, an edited connection is saved even when the test fails — it then gets the Unavailable status.
Deleting a connection
A connection is deleted from the list through a confirmation dialog. If project versions were imported through the connection being deleted, a warning listing those versions (in the "project / version" form) is shown after the deletion: these versions lose the reference to the connection they were obtained through.
Use in version export and import
In the version export and import dialogs the user selects a Git connection from the list of the company's connections. The dialog uses the connection's default branch, offers the actual list of the repository's branches, and allows creating a new branch. The commit is made on behalf of the DataForge user (their name and email), with a user-defined commit message. If the selected connection fails during the transfer, a message with the reason is shown and the connection should be re-tested; if the connection has been deleted, the message "Selected Git connection no longer exists." is shown. Version export and import themselves are described on their own page in the Projects section.