When you create a new project, it only exists in Development Mode to let you develop your model in a safe environment that will not impact other users. Once you’re ready to publish your project, the next step is to configure a Git connection.

Configuring a Git connection for your project lets you deploy your LookML to Production Mode, which lets other users explore your data model, build dashboards, and add LookML to your model. For a quicker setup, use a bare repository. For a more robust Git integration, create your own Git repository and follow the instructions on this page to connect it to your Looker instance.

Integrating Looker with Git

Looker uses Git to record changes and manage file versions. Each LookML project corresponds to a Git repository, and any time a user is in Development Mode that user is on their own Git branch. Git repositories are often called repos.

For LookML source file management, Looker can be configured with any Git provider that uses an SSH key or HTTPS for authentication. The general steps are the same no matter which platform you use. This page uses GitHub as an example for connecting a Looker project to Git once you have created a Git repository.

To access Git integration options, you must have Development Mode turned on.

You can configure Git integration using one of the following protocols:

• HTTPS: HyperText Transfer Protocol Secure. With HTTPS, Looker accesses your Git repository with a username and password (or access token) that you provide, as described in Connecting to Git Using HTTPS below.
• SSH: Secure Shell. With SSH, Looker accesses your Git repository using a deploy key that you generate through your Git provider’s website, as described in Connecting to Git Using SSH below.

Connecting to Git using HTTPS

GitHub does not accept account passwords for authenticating Git operations on github.com. See GitHub’s blog post for more information. To connect a Looker project to GitHub using HTTPS, use the developer settings in GitHub to create a personal access token. For existing Looker projects that connect to GitHub using HTTPS, reset your Git connection using a personal access token from GitHub.

For LookML projects configured with HTTPS authentication, Looker connects to your Git provider with one or more user accounts that you set up with your Git provider. Looker uses a username and password (or access token) to log in to your Git provider and perform Git operations on behalf of your LookML developers.

If your Git account uses two-factor authentication, you can go to your Git provider and create access tokens to use instead of passwords. Go to this Community topic to see instructions for creating personal access tokens for common Git providers.

With HTTPS authentication, you can configure your LookML project to use a single Git account for the entire project, or you can configure the project to use your developers’ individual Git accounts to perform their Git operations.

Single account HTTPS authentication

If you set up your LookML project with a single Git account, Looker uses that Git account to log in to your Git provider to commit changes on behalf of the developers. Looker makes these commits using the developer’s Looker username so you can tell which developer made each commit. You can see your project’s commit history on your Git provider’s interface or by selecting the History option from the Git menu of the Looker IDE. See Executing Git Commands in Looker for more information on the Git menus in Looker.

For single account HTTPS authentication, the Git user account you specify must have read and write access to your Git repository. Your LookML developers themselves do not need to have their own Git user accounts.

Multiple account HTTPS authentication with user attributes

If you set up your LookML project with multiple accounts, your LookML project will use each Looker developer’s individual Git account to perform Git operations. You also need to configure one generic Git user account, with at least read access, that Looker will use to pull the production version of the files.

The following tasks and requirements are needed for Git authentication with user attributes:

• Each of your LookML developers must have their own user account with your Git provider. Each Git user account must have read and write access to the project’s repository.
• Your Looker admin must set up Looker user accounts with user attributes corresponding to Git username and Git password (or access token if the Git user accounts have two-factor authentication).
• User attributes for Git account passwords (or access tokens) must be hidden. When you create the password or access token attribute, select Yes under the Hide Values option and enter the Git provider URL in the Domain Allowlist field.
• The user attributes for Git name and password (or access token) must be filled in for each Looker developer. User attributes can be configured by a Looker admin or by the Looker user.

Here is an example of the User Attributes admin page where a Looker admin has set up user attributes for Git username and user access token:

Here is an example of a Looker user’s Account page where the user has entered their Git credentials into their user attribute fields:

Configuring HTTPS Git authentication

To configure a LookML project with HTTPS Git authentication:

1. Get the HTTPS URL for your Git repo. In the case of GitHub, for new repositories (repositories that don’t yet contain any files), GitHub will show you the URL as part of the initial setup. Be sure to click the HTTPS button so you get the HTTPS URL, then click the copy button to copy it to your clipboard:

   

   For existing GitHub repositories (repositories that already contain files), you can see the HTTPS URL by going to the repository’s Code tab and clicking on the Code button. Be sure to click the HTTPS link. You can click the clipboard icon to copy to your clipboard:

   

2. Navigate to your LookML project, click the Settings icon from the navigation bar, and scroll down to the Configure Git section (for new projects) or the Reset Git Connection section (for existing projects that have been connected to Git previously):

   Resetting your Git connection will preserve Git history for the master branch. It will also preserve the history of each Looker developer’s personal branch once they pull, merge, and deploy. To preserve history for all branches, see the Migrating to a new Git repository Help Center article.

   

3. In Looker’s Configure Git section, paste the HTTPS URL for your Git repository in the Repository URL field, then click Continue.

   

   Looker will detect your Git provider and update the window with information about your Git repository:

   

   If Looker does not successfully detect your Git provider, it will ask you to choose from a drop-down.

4. Select your Git login option:

   • Use a single, constant username and password/token combination (see Single account HTTPS authentication).
   • Use user attributes for username and password/token (see User attribute HTTPS authentication).

5. In the Username and Password/Personal Access Token fields, enter the credentials that your LookML project will use to access Git. This is required regardless of your Git login setting:

   • If you selected Use a single, constant username and password/personal access token combination, this is the Git username and password (or access token) that your Looker instance will use for all Git operations. This Git user account must have read and write access to your Git repository.
   • If you selected Use user attributes for username and password/personal access token, this is the Git username and password (or access token) that your Looker instance will use to pull the production version of the repository. This Git user account must have at least read access to your Git repository.

   If your Git account uses two-factor authentication, or if you are using GitHub (which requires a personal access token instead of a password), you can go to your Git provider and create access tokens to use instead of passwords. Go to this Community topic to see instructions for creating personal access tokens for common Git providers.

6. If you selected Use user attributes for username and password/personal access token, you will see the user attribute settings. Use the drop-down menus to select the user attributes for individual developer’s Git credentials:

   

   (Looker users can edit the values for their user attribute fields on their Account page, or Looker admins can edit the user attribute values for a user on the Users admin page.)

7. Click Continue Setup.

Git is now configured for your LookML project. From here you can validate your LookML, and then create your initial commit and deploy to production to make your project available in Production Mode. You can also:

• Use the Git menu to access the Git commands.
• Use the Git menu to test your Git connection.
• If you are a Looker admin, go to the Project Settings page to require LookML validation and to configure Git integration options.

Connecting to Git using SSH

With SSH authentication, you create a deploy key for your Git provider. Looker generates the SSH key pair and displays the public key in the UI, as seen in step 4 below. Looker uses that deploy key to log in to your Git provider to commit changes on behalf of the Looker developers. Looker makes commits using a developer’s Looker username so you can tell which developer made each commit. You can see your project’s commit history on your Git provider’s interface or by selecting the History option from the Git menu of the Looker IDE. See Executing Git Commands in Looker for more information on the Git menus in Looker.

To configure a LookML project with SSH Git authentication:

1. Open your project and select Configuration in the project settings panel to view the project configuration. Then, do one of the following:

   • For a new project, select the Configure Git button in the project configuration section.
   • To change the Git setup for an existing project, select Reset Git Connection in the project configuration section.

   Resetting your Git connection will preserve Git history for the master branch. It will also preserve the history of each Looker developer’s personal branch once they pull, merge, and deploy. To preserve history for all branches, see the Migrating to a new Git repository Help Center article.

   

2. Get the SSH URL for your Git repo. Here are the formats for common Git providers:

   • GitHub: git@github.com:<organization-name>/<repository-name>.git
   • GitHub Enterprise: git@example.com:<organization-name>/<repository-name>.git
   • Cloud Source Repositories: ssh://username@example.com@source.developers.google.com:2022/p/<project-id>/r/<repository-name>
   • GitLab: git@gitlab.com:<organization-name>/<repository-name>.git
   • Bitbucket: git@bitbucket.org:<organization-name>/<repository-name>.git
   • Phabricator: ssh://username@example.com/diffusion/MYCALLSIGN/<repository-name>.git

   In the case of GitHub, for new repositories (repositories that don’t yet contain any files), GitHub will show you the SSH URL as part of the initial setup. Be sure to click the SSH button so you get the SSH URL, then click the clipboard icon to copy it to your clipboard:

   

   For existing GitHub repositories (repositories that already contain files), you can see the SSH URL by going to the repository’s Code tab and clicking on the Code button. Be sure to click the Use SSH link. You can click the clipboard icon to copy to your clipboard:

   

3. In Looker’s Configure Git section, paste the SSH URL for your Git repository in the Repository URL field, then click Continue.

   URLs with custom or non-standard Git ports can be used with Looker by adding the non-standard port number to the Git URL. For example: ssh://git@corporate.git.server.com:22/myorganization/myproject.git
   You must include the ssh:// for this to work properly.

   

4. Looker will detect your Git provider and display a deploy key for your repo. (If Looker does not successfully detect your Git provider, it will ask you to choose from a drop-down.) Select the entire deploy key and copy it to your clipboard, then click on the Deploy Key settings for your repository link to open the GitHub Deploy keys page for your GitHub repository.

   

5. In the GitHub Deploy keys page, click on the Add deploy key button:

   

   GitHub displays the Deploy keys / Add new page:

   

6. Add a title for the deploy key. The name isn’t important, but you might want to include “Looker” and your project title to keep track of it in the future.

7. Paste the deploy key that you copied from Looker.
8. Select the Allow write access option.
   This is an important step, because Looker requires this setting in order to make and deploy changes to your LookML model.
9. Click the Add key button. (At this point, your Git provider may prompt you to enter your password. If so, enter your password and then click Confirm password.)
10. GitHub will show all the deploy keys that have been added for your repository.

11. Go back to your Looker window and click Test and Finalize Setup in the Configure Git section. If there is a problem with your Git setup, you will see an error like this:

    

From here, you can try again to set up the deploy key, or you can click Skip Tests and Finalize Setup to keep your current settings.

Git is now configured for your LookML project. From here you can validate your LookML, and then create your initial commit and deploy to production to make your project available in Production Mode. You can also:

• Use the Git menu to access the Git commands.
• Use the Git menu to test your Git connection.
• If you are a Looker admin, go to the Project Settings page to require LookML validation and to configure Git integration options.

Configuring a bare Git repository

If you haven’t yet created a remote Git repository, or just want to get set up quickly so others can benefit from your LookML, you can configure a bare Git repository. Configuring a bare Git repository creates a local Git repository on your Looker instance, rather than connecting to a remote repository.

To configure a LookML project with a bare Git repository:

1. Open your project and select Configuration in the project settings panel to view the project configuration. Then, do one of the following:

   • For a new project, select the Configure Git button in the project configuration section.
   • To change the Git setup for an existing project, select Reset Git Connection in the project configuration section.

   Resetting your Git connection will preserve Git history for the master branch. It will also preserve the history of each Looker developer’s personal branch once they pull and merge and then deploy. To preserve history for all branches, see the Migrating to a new Git repository Help Center article.

   

2. In Looker’s Configure Git dialog box, click Set up a bare repository instead.

   

3. In the Configure Bare Git Repository dialog box, click Create Repository.

   After creating the Git repository, Looker displays a dialog box showing the path to the new Git repository:

   

Git is now configured for your LookML project. From here you can validate your LookML, and then create your initial commit and deploy to production to make your project available in Production Mode. You can also:

• Use the Git menu to access the Git commands.
• Use the Git menu to test your Git connection.
• If you are a Looker admin, go to the Project Settings page to require LookML validation and to configure Git integration options.

Testing your Git connection

Looker provides a Git connection test to verify your Git connection. The Git connection test verifies that you’ve set up the correct Git URL and that the Git host is reachable by Looker. The Git connection test also verifies that you have provided a valid Git deploy key and that the deploy key has write access to your Git repository.

If Looker is unable to connect to your Git repository, you will see the Test Git Connection button:

You can also access the Git connection test tool by selecting Test Git Connection in the Git actions panel:

The Git connection test tool then displays the steps it is taking to test the Git connection. Here is an example of a successful test:

In this example, the Git repository does not have a deploy key configured for the Looker connection: