Git Sync
Deploy projects from a Git repository, commit project changes back to one, or sync both ways.
Git Sync connects a project to a Git repository, in one of three directions:
- Pull deploys from Git. You edit in Git; Arcane copies the files in and can redeploy.
- Push backs up to Git. You edit in Arcane; Arcane commits the files.
- Pull and push syncs both ways. You edit in either place; Arcane pulls repository changes and commits yours.
A project has one sync. To change direction, disconnect it and create a new one. Syncs from every agent are on the Git Syncs page, with an Agent column and filter.
Connect a repository
Section titled “Connect a repository”- Go to Git Syncs → Git Repositories and click Add Repository.
- Enter the repository URL and a name.
- Optional: set Git Provider to GitHub, GitLab, Gitea / Forgejo, or Bitbucket. It sets the link format for files and commits. The default, Detect from URL, guesses it from the repository URL.
- Choose an Authentication Type:
- HTTP (Username/Token): a username and personal access token.
- SSH Key: use this if you already connect to Git over SSH.
- For SSH, choose a Host Key Verification mode:
- Accept New (default): accept the server’s key on first connect and save it.
- Strict: only connect if the server key is already known.
- Skip Verification: no check. Insecure.
- Save. For Push, the credentials need write access to the branch.
Pull from Git
Section titled “Pull from Git”Create a Git-synced project
Section titled “Create a Git-synced project”- On Projects, open the dropdown next to Create Project and choose From Git Repo. Or click Add Sync on Git Syncs and pick the Agent.
- Choose Pull and enter a Sync Name, which becomes the project name.
- Leave Target Type as Project (Stack deploys to a Swarm stack).
- Leave Project as Create a new project, or pick an existing project to link.
- Pick the Git Repository and Branch, then set the Compose File Path relative to the repository root, or click the folder icon to browse.
- Optional: set a Compose Override File and Environment Variables.
- Optional: turn on Sync Files, Auto Sync with a Sync Interval in minutes, Pull Image After Sync, or Redeploy After Sync.
- Click Add Sync.
Sync the whole folder
Section titled “Sync the whole folder”By default, only the Compose file is copied. Sync Files copies its whole folder, including files for include, extends, and relative paths. The copied files are read-only in the workspace.
New syncs take their copy limits from Settings → Storage & Limits → Git Sync File Limits: Max Synced Files (default 500), Max Total Size (MB) (default 50), and Max Binary Size (MB) (default 10). Use 0 to remove a cap. A limit set by environment variable overrides every sync’s own value.
Pre-deploy hooks, which run a script before each deploy, need Sync Files on.
Override file and variables
Section titled “Override file and variables”Compose Override File sets the override Arcane merges over the Compose file:
- Leave it empty to use
compose.override.ymlorcompose.override.yamlnext to the Compose file. - Or enter a
.ymlor.yamlpath relative to the repository root, or click the folder icon to browse. It can’t be the Compose file itself. - With Sync Files on, a Project target only uses
compose.override.yamlbeside the Compose file. Rename the file, or list it inCOMPOSE_FILE. - If the project’s Compose file has a custom name, a sync that brings an override fails. Rename the Compose file to
compose.yaml.
Environment Variables takes KEY=VALUE lines. Arcane merges them over the repository’s .env on every sync, so they replace repository values. Load .env file appends a file’s contents to the field. Clearing the field removes those values on the next sync.
In the API, these are composeOverridePath and envContent. JSON import doesn’t accept them.
Edit a Git-synced project
Section titled “Edit a Git-synced project”The Compose file is read-only for Pull projects.
- Click Open Project in Git or Edit File in Git.
- Edit and commit on the Git host.
- In Arcane, click Sync from Git.
.env stays editable in Arcane:
- Arcane merges the repository’s
.env.gitwith yourproject.envedits into.env. - Your values win. They replace keys in place, keeping order and inline comments. New keys are appended.
- To pass the values to services, add
env_file: .envto the Compose file.
Import multiple syncs from JSON
Section titled “Import multiple syncs from JSON”- On Git Syncs, click Import .JSON.
- Pick the Agent.
- Paste or upload a JSON array of Pull syncs. Fields are under Reference.
[ { "syncName": "project-name", "gitRepo": "my-git-repo", "branch": "main", "dockerComposePath": "compose/myproject/compose.yaml", "autoSync": true, "syncInterval": 5, "syncDirectory": true }]Push to Git
Section titled “Push to Git”Pushing doesn’t deploy or restart the project; its files stay editable in Arcane.
Set the commit identity
Section titled “Set the commit identity”Before the first push, edit the repository under Git Syncs → Git Repositories:
- Commit identity: Author name and Author email. Blank means
Arcane<arcane@localhost>. - GPG signing key: paste an armored OpenPGP private key (and its Signing key passphrase, if any) to sign commits; otherwise they’re unsigned. It’s separate from the SSH connection key. Clear stored signing key removes it.
Set up a push sync
Section titled “Set up a push sync”- On the project’s Git Backup tab, click Back up to Git. Or click Add Sync on Git Syncs, choose Push, and select the Project.
- Pick the repository and branch.
- Set Destination folder to a path inside the repository, such as
projects/my-app, without a leading/. - Under Included files, select extra files or directories. Leave Include environment file off unless you want to commit
.env. - Choose when to push: Back up on save (default on) pushes after you save in Arcane; Automatic backup checks on a schedule. Turn both off for manual only.
- Click Save and back up to run the first push.
Use a separate folder per project. Arcane rejects folders that overlap another push sync on the same branch. To move a folder, disconnect and recreate the sync.
Choose what to commit
Section titled “Choose what to commit”- Push always includes the Compose file and detected overrides.
- Included files adds other workspace files or directories, binary or text.
- Include environment file adds
.env. - Select other environment files one by one. Selecting their parent directory doesn’t include them.
Push backs up project configuration only; use backups for data in Docker volumes.
Check a push
Section titled “Check a push”The project’s Git Backup tab shows pending changes, the last push, and errors.
- To push now, click Back up now.
- To see earlier commits, open the history.
- Arcane commits only when selected files differ.
- Files you delete or deselect, including
.env, are removed on the next push. Other repository files are left alone.
Resolve repository changes
Section titled “Resolve repository changes”Arcane pauses the sync as Needs attention when someone changes files Arcane pushed, or when the first push would overwrite existing files.
- Open the conflict details.
- Pick one:
- Use Arcane files overwrites them in a new commit. History is kept.
- To keep the repository’s version, copy the changes into the project first. Or disconnect and choose another folder.
Push never pulls changes into the project; use Pull and push for that. Disconnecting a push sync stops future pushes and keeps the local files and repository history.
Pull and push
Section titled “Pull and push”One sync pulls repository changes into the project and commits changes made in Arcane. The project’s files stay editable in Arcane. It needs gitops:bidirectional and a repository with write access to the branch.
Set up a two-way sync
Section titled “Set up a two-way sync”- On the project’s Git Backup tab, click Add Git Sync. Or click Add Sync on Git Syncs.
- Choose Pull and push and select the Project. Projects that already have a sync aren’t listed.
- Pick the repository and branch, and set the commit identity on the repository.
- Set Destination folder to the project’s folder inside the repository, such as
projects/my-app. - Under Included files, select extra files or directories. The Compose file is always included.
- Optional: turn on Sync Files to also pull new repository files inside the included folders.
- Choose when to sync: Commit on save (default on) commits after you save in Arcane; Auto Sync checks the repository on a schedule.
- Optional: set Environment Variables, Pull Image After Sync, or Redeploy After Sync. They work as in Pull.
- Save the sync.
A two-way sync differs from the other directions:
- It targets a project, never a Swarm stack.
- It has no Compose Override File field and no Max Binary Size limit.
- Environment files aren’t synced. Arcane’s own
.envis never pushed or pulled. - The project name is set by the sync and can’t be changed on the project page.
Run a sync
Section titled “Run a sync”On the project’s Git Sync tab, click Sync Now. Save or discard unsaved edits first.
Each run does three things in order:
- Compares every file with the last synced version, in Arcane and in the repository.
- Pulls files changed only in the repository, and deploys as a Pull sync would.
- Commits files changed only in Arcane.
A file deleted on one side is deleted on the other. The tab shows the sync status, the files in the last sync, and recent syncs.
Resolve conflicts
Section titled “Resolve conflicts”A file changed on both sides is a conflict. Arcane pauses the sync as Needs attention and changes nothing on either side.
- Open Resolve Conflicts to see the conflicting files.
- Pick one:
- Use Arcane files keeps Arcane’s version of the conflicting files.
- Use repository files takes the repository’s version of the conflicting files.
Either choice applies only to the conflicting files. All other changes still sync both ways. Arcane never force-pushes; the losing version stays in Git history when it was committed.
Disconnecting a two-way sync stops pulling and pushing. The project, its files, and the repository history are kept.
Reference
Section titled “Reference”JSON import fields
Section titled “JSON import fields”| Field | Required | Description |
|---|---|---|
syncName |
Yes | Sync name. Also the project name unless projectName is set. |
gitRepo |
Yes | Name of a repository already added under Git Repositories. |
branch |
Yes | Branch to sync from. |
dockerComposePath |
Yes | Compose file path relative to the repository root. |
autoSync |
Yes | Check for changes on a schedule. |
syncInterval |
Yes | Minutes between automatic syncs. |
syncDirectory |
No | Same as Sync Files: copy the Compose file’s whole folder. |
projectName |
No | Project name, if different from syncName. |
pullImageAfterSync |
No | Same as Pull Image After Sync. |
redeployAfterSync |
No | Same as Redeploy After Sync. |
maxSyncFiles |
No | Maximum number of files copied per sync. |
maxSyncTotalSize |
No | Maximum combined size of synced files, in bytes. |
maxSyncBinarySize |
No | Maximum size of a single binary file, in bytes. |
preDeployScriptPath |
No | Path to a pre-deploy script. Requires syncDirectory: true. |
preDeployRunnerImage, preDeployEnv, preDeployExtraMounts, preDeployTimeoutSec, preDeployNetworkMode |
No | Other pre-deploy hook settings. Require gitops:lifecycle. |