Authorize a service principal to access Git folders

A service principal is a non-human identity used to authenticate automated workflows in Databricks. This page explains how to authorize a service principal to use Git credentials for Git folder operations.

Add Git credentials using the Databricks UI

To link Git credentials to a service principal:

1. As a workspace admin, log in to the Databricks workspace.
2. Click your username in the top bar and select Settings.
3. Click the Identity and access tab.
4. Next to Service principals, click Manage.
5. Select the service principal that you want to update with Git credentials.
6. Click the Git integration tab.
7. Click Add Git credential.
8. Choose the Git provider from the dropdown menu and fill out the required fields.
9. Click Save or Link, depending on which provider you chose.

The service principal now uses the linked Git credentials when accessing your Databricks workspace Git folder resources as part of your automation.

Add Git credentials using the Databricks CLI

Configure service principal Git access using the Databricks CLI for automation workflows.

note

Before you begin, verify that you have:

• The Databricks CLI installed and configured.
• A personal access token from your Git provider. See Configure Git credentials & connect a remote repo to Databricks.

To provide authorized access to your Git folders for service principals using the Databricks CLI:

1. Create a service principal in your workspace:

   Bash

   databricks service-principals create --display-name "Git Automation Service Principal"

   Note the applicationId and id values from the output. You'll need them in the next steps.

2. Generate an OAuth secret for the service principal:

   Bash

   databricks service-principal-secrets-proxy create <service-principal-id>

   Replace <service-principal-id> with the 15-digit id value from the previous step.

   Copy the secret value from the output.

3. Add Git provider credentials for the service principal.

   Configure the Databricks CLI to authenticate as the service principal using OAuth:

   Bash

   export DATABRICKS_HOST=<workspace-url>
   export DATABRICKS_CLIENT_ID=<application-id>
   export DATABRICKS_CLIENT_SECRET=<oauth-secret>

   Replace:

   • <workspace-url> with your workspace URL
   • <application-id> with the application ID from step 1
   • <oauth-secret> with the OAuth secret from step 2

   Then add the Git credentials:

   Bash

   databricks git-credentials create <git-provider> \
     --personal-access-token <git-pat> \
     --git-email <git-email>

   Replace:

   • <git-provider> with your provider, such as gitHub or gitLab
   • <git-pat> with your Git provider personal access token
   • <git-email> with your Git email address

   Some Git providers require --git-username or --git-email to properly authenticate. GitHub, for example, requires at least one of these parameters.

The service principal can now access Git folders using the linked credentials.

Retrieve service principals programmatically

Retrieve service principals for your workspace using the Databricks SDK, REST APIs, or CLI.

To use the Databricks SDK from a notebook:

1. Install the Databricks SDK: %pip install databricks-sdk --upgrade
2. Import ApiClient from databricks.sdk.core.
3. Call the service principals API.

For code examples, see the Databricks SDK for Python documentation.

You can also use curl, the Databricks CLI, or Terraform to work with service principals programmatically.

Next steps

• Manage service principals
• Use service principals for CI/CD
• Automate Git folder operations with Terraform