Databricks Git folder pull or push fails: expired credentials, merge conflicts, private repos behind a firewall and jobs on the wrong commit

#Symptoms

• Pull in a Git folder fails with Error fetching Git status / Invalid Git credentials / Missing Git credentials.
• Push fails with Push rejected or Error pushing changes: remote has changes not present locally.
• The Git folder is stuck in a merge state or shows conflicts you can't resolve in the UI.
• Connecting to an on-prem Azure DevOps Server or GitHub Enterprise fails with timeouts.
• A job ran old code even though the change was merged.

#Step 1: Credentials

Each user's Git credential is stored in User settings > Linked accounts (Git integration). Jobs use the credential of the job's run-as identity.

Update credentials from the CLI (handy for service principals running jobs):

databricks git-credentials list
databricks git-credentials create azureDevOpsServices \
  --personal-access-token "$ADO_PAT" --git-username "svc-databricks@example.com"
# or update an existing one
databricks git-credentials update <credential-id> azureDevOpsServices \
  --personal-access-token "$ADO_PAT" --git-username "svc-databricks@example.com"

Provider names include gitHub, gitHubEnterprise, azureDevOpsServices, bitbucketCloud, gitLab and others; check databricks git-credentials create --help for the exact spelling in your CLI version.

Tip

Give service principals that run jobs their own Git credential (a PAT or GitHub App from a service account), not a person's PAT. When that person leaves, jobs break.

#Step 2: Push rejected: remote has new commits

Someone else pushed to the branch. In the Git dialog: Pull first, then push. If pull reports conflicts, see Step 3.

Avoid it by having each developer work in their own Git folder (under /Workspace/Users/<you>/) on their own feature branch, and merging through pull requests in the Git provider. Two people editing the same branch in one shared Git folder is the most common source of conflicts and lost edits.

#Step 3: Resolve conflicts without losing work

The Git folder UI shows conflicted files and lets you pick versions or edit. If it gets confusing:

1. Save your work outside Git first: export the notebooks you changed (File > Export > Source file) or copy them to a scratch folder.
2. In the Git dialog, abort the merge if offered, or use Reset to the remote branch.
3. Re-apply your changes from the exported copy on a fresh feature branch, commit, push, and open a PR.

Caution

Reset (hard reset) in a Git folder discards uncommitted local changes. Export anything you need first.

Notebook conflicts are harder to read than plain files. Store notebooks in source format (.py with # Databricks notebook source or .ipynb consistently) and agree on one format per repo so diffs stay readable.

#Step 4: Git server not reachable

Azure DevOps Services and GitHub.com are reached from the Databricks control plane. On-prem or private Git servers (Azure DevOps Server, GitHub Enterprise Server behind a firewall) aren't reachable from there by default.

Options:

• Allow the Databricks control plane egress IPs for your region on the Git server's firewall (IP list in the Azure Databricks docs).
• Use Git server proxy for Git folders: a small proxy cluster in your workspace's VNet that forwards Git traffic from the control plane to your private Git server. It's set up by an admin following the Databricks guide.

Test reachability from a cluster in your VNet:

%sh
curl -sS -o /dev/null -w '%{http_code}\n' https://git.example.internal/tfs/DefaultCollection/_apis/projects

A response from the cluster but failures in the Git folder UI usually means the proxy isn't set up or isn't running.

#Step 5: Jobs ran the wrong code

Two ways jobs use Git:

Use git_source for production jobs:

{
  "git_source": {
    "git_url": "https://dev.azure.com/org/data/_git/pipelines",
    "git_provider": "azureDevOpsServices",
    "git_branch": "main"
  },
  "tasks": [
    { "task_key": "orders", "notebook_task": { "notebook_path": "orders/silver", "source": "GIT" } }
  ]
}

For stricter control, pin git_tag or git_commit and update it through your release pipeline. Or deploy with Databricks Asset Bundles, which copy code to a deployment folder per target so the workspace runs exactly what CI deployed.

If you keep production Git folders, update them only from CI:

databricks repos update /Workspace/Repos/prod/pipelines --branch main

and restrict Can Manage / Can Edit on that folder to the CI service principal.

#Symptom → fix table

#Prevent it next time

• Personal Git folders and feature branches for development; PRs for merging.
• Service principal Git credentials for jobs, with expiry tracked and rotated before it lapses.
• Production jobs from git_source or Asset Bundles, never from a folder people can switch.
• Branch protection on main in the Git provider.