Git remote
Git remote (/settings/git-remote, under Settings in the sidebar) says where the engine
pushes the mapping history, how, and as whom. History, reviews and releases are on the
Versioning page. Like Versioning, this page is listed only when versioning is available (see
When is versioning available). Connecting a repository step by step
is in Connect a Git repository.
A GitHub repository after Test connection.
- 1 Git remote
The page title, with its help link.
- 2 Whole tenant
“These settings apply to the whole tenant tenant. Everyone who signs in to it pushes to this repository and branch with this token, and a change here changes it for all of them.”
- 3 Repository URL
The repository’s clone URL, for example
https://github.com/acme/mappings.git. Save needs it.- 4 Branch
The branch the engine pushes to, for example
main.- 5 Username
Leave empty to let the engine detect it from the provider.
- 6 Access token
Once a token is stored, the label says “stored (…last characters); leave empty to keep it”. Type a new token only to replace it. “Pushes and pull requests run as the token’s owner. Use a bot account or a project access token limited to this repository, not a personal one.” The token stays with the hosts it was given for. A save that would send it to another repository host, to an API base on a host of its own, or (for a token stored before any repository) to the first repository removes it unless a new one is typed: an amber note then replaces “leave empty to keep it” (“The stored token was given for old host. Changing the host removes it; enter a token for new host.”), and saving says “Saved. The token was removed because the host changed.” Turning on a provider whose API is on the repository’s host (or is github.com’s) keeps it. See Move to another repository host.
- 7 Remove
Deletes the stored token.
- 8 Provider
Detect from the URL, GitHub, GitLab, Gitea / Forgejo or Plain git (no pull requests). Detected again from a new repository URL unless you change it in the same save.
- 9 Provider API base
The provider’s API address, used for pull requests, release links and checks. Left empty, it is detected from the URL; like the provider, it is detected again from a new repository URL unless you change it in the same save.
- 10 Workflow
Direct — push to the branch, or Review — changes go through pull requests (not with plain git).
- 11 Commit author e-mail (optional)
Leave empty to use each user’s own e-mail. When set, it is “Used for every user’s commits.”
- 12 Push automatically
Never — push by hand, After a change — once edits pause, or On an interval — every N min with changes. With the review workflow it reads Off with the review workflow: changes reach the branch as pull requests you submit.
- 13 Group edits within (minutes)
Edits within this many minutes go into one commit. With On an interval it is also the push interval.
- 14 Save
Saves the settings (“Saved.”).
- 15 Test connection
Checks that the remote is reachable with these settings. Enabled once the settings are saved.
- 16 Disconnect
Asks Disconnect the git remote: “Disconnect the git remote? The engine keeps its journal; nothing is deleted from the remote.”
- 17 Connection
The result of the test: The remote is reachable. (or why not), whether the branch exists and has content, the branches found, and whether the token may push.
- 18 First connection
Before the first push: “Push the engine’s current state as the first commit of the branch.” with Connect. If the branch already has content, Atlas says “The branch already has content. Which side wins?”: The engine — commit its state over the branch or The repository — import it into the engine (imports right away). Once connected it shows the last push. If the branch was deleted since, it says “The engine pushed before, but branch has no commits now (deleted?).” and offers Connect again. See When the branch already has content and When the branch was deleted.
The page can also warn that the engine has no secret key configured (so it can’t store a token), or that no API base URL is stored for the provider (“Save to use the default, or enter the URL of your own server.”).