Git Integration

Looker uses Git to record changes and manage file versions. Each LookML project corresponds with a Git repository, and each user’s development mode correlates to a 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.

If your Git repo is hosted by Looker, talk to your Looker analyst or the chat team for help with setting up Git.

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 user name 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

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 user name 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 user name 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 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:

• Your LookML developers each 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 user name and Git password (or access token if the Git user accounts have two-factor authentication).
• The user attributes for Git name and password (or access token) must be filled in for each 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 user name and password:

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. Open your project in Looker and then do one of the following:

   • For a new project, click the Configure Git button.
   • If you want to change the Git setup for an existing project, click on the Git menu and select Project Settings, then click the Reset Git Connection button from the Project Settings page.

   Resetting your Git connection will erase your Git history. In order to preserve the Git history for existing Git connections, see this Help Center article.

   

2. 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 Clone or download button. Be sure to click the Use HTTPS link. You can click the copy button to copy to your clipboard:

   

3. In Looker’s Configure Git screen, paste the HTTPS URL for your Git repository, 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 combination (see Single Account HTTPS Authentication)
   • Use user attributes for username and password (see User Attribute HTTPS Authentication)

5. In the Username and Password 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 combination, this is the Git user name and password 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, this is the Git user name and password 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, 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, 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.
• 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 through your Git provider. Looker uses that deploy key to log in to your Git provider to commit changes on behalf of the developers. Looker makes commits using a developer’s Looker user name 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 in Looker and then do one of the following:

   • For a new project, click the Configure Git button.
   • If you want to change the Git setup for an existing project, click on the Git menu and select Project Settings, then click the Reset Git Connection button from the Project Settings page.

   Resetting your Git connection will erase your Git history. In order to preserve the Git history for existing Git connections, see this 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
   • 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 copy button 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 Clone or download button. Be sure to click the Use SSH link. You can click the button to copy to your clipboard:

   

3. In Looker’s Configure Git screen, paste the SSH URL for your Git repository, 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 Deploy keys page for your GitHub repository.

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

   

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 then click Confirm password.)
10. GitHub will show all of 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 screen. 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.
• Go to the Project Settings page to require LookML validation and to configure Git integration options.

Git Connection Test Tool

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 at any time by holding Shift while clicking the Git menu:

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:

Project Settings

The Project Settings page has additional configuration options for your project. To see this page, open your project and select Project Settings from the Git menu:

On the Configuration tab of the Projects Settings page, you can configure:

• Name: The name of your project. You can rename your project by editing the text and clicking the Save Project Settings button. See this page for more details.
• Code Quality: Determines whether to require developers to successfully run the LookML Validator on the project before committing any changes to the project. Code Quality has the following options:
  • Require fixing errors and warnings before committing: Developers can commit changes only after successfully running the LookML Validator and resolving all errors and warnings. This is the recommended setting.
  • Only require fixing errors before committing: Developers can commit changes only after successfully running the LookML Validator and resolving all errors. Developers can commit changes when warnings exist. While not recommended, this option can be useful, for example, if new warnings are introduced to working LookML after a Looker upgrade.
  • Allow committing broken code: Developers can commit changes without running the LookML Validator and regardless of whether errors or warnings exist in the LookML. This option is not recommended as it can result in LookML that doesn’t function or that produces erroneous results.
• Git Integration: The levels of integration with your Git provider. See Git Integration Options for details.
• Webhook Deploy Secret: Set up authentication for deploying changes to production on your Looker instance. See Webhook Deploy Secret for details.
• Reset Git Connection: This button opens the Configure Git window, where you can update the connection settings for your Git repository.
• Delete Project: This button deletes the project, removing all LookML from the project, in all development and production environments across your Looker instance.

Resetting your Git connection will erase your Git history. In order to preserve Git history, see this Community topic.

On the Branch Management tab of the Projects Settings page, you can see all the Git branches associated with the project. See this page for details on the Branch Management tab.

At the bottom of the Projects Settings page, you also can see your project’s current Git settings:

Git Integration Options

Once you set up your Git connection, Looker will use your Git provider for managing your LookML source files, as described on this page. That’s all you need to do to set up your project with source file management and version control. However, you can configure additional options for Looker’s integration with Git using the Git Integration options on the Project Settings page.

In this example, we’re using GitHub, so the window shows GitHub Integration. However, if you are using a different Git provider, Looker will display your Git provider’s name instead.

Here’s what these Git integration options do:

• Off: Looker will fully use your Git provider for managing LookML files, but Looker won’t display any external links to your Git provider’s interface.
• Show Links: Looker will provide external links to your Git provider’s interface so that your developers can view the project in the Git provider’s interface. Also, Looker will provide links for each project file so that your developers can view the file’s history and Git blame information on your Git provider’s interface. See the Integrating External Links to Your Git Provider section for information about the links.
• Pull Requests Recommended: In addition to providing external links to your Git provider’s interface, Looker will allow developers to submit a pull request so that another developer can approve changes before adding them to the project. See this section for information on setting this up.
• Pull Requests Required: This is the same as above, except that your LookML developers are required to open a pull request to submit changes to the project. See the Integrating Pull Requests for Your Project section for information on setting this up.

The Pull Requests Recommended and Pull Requests Required options are only shown if you are self-hosting your repository using a Git provider as described in this section.

If you change your Git integration option, click Save Project Settings to save your new setting.

Integrating External Links to Your Git Provider

If you have enabled any of the extra Git integration options (Show Links, Pull Requests Recommended, or Pull Requests Required), Looker provides external links to your Git provider’s interface. These external links open a new browser tab to your Git provider’s site.

To view these external links, your developers must have an account with your Git provider, and must have access to the project’s Git repository.

In the gear menu for each of your LookML files, Looker provides links to your Git provider’s site to view the file, view the Git blame information for the file, and to view the commit history for the file:

In the Git menu, Looker provides a link to your project files on your Git provider’s site:

Integrating Pull Requests for Your Project

By default, Looker developers can commit and deploy their changes to production. However, instead of letting developers deploy their own changes to production, you can also set up your project with either the Pull Requests Recommended or the Pull Requests Required option.

The Pull Requests Recommended and Pull Requests Required options are only available if you are self-hosting your repository using a Git provider; these options won’t be shown if you are using a Looker-hosted repository for your LookML files. See this Community topic for information about moving from a Looker-hosted repository to a self-hosted repository.

With either Pull Requests Recommended or Pull Requests Required, developers submit a Git pull request for the changes on their branch. The pull request can then be reviewed and approved by other developers before being deployed to production through your Git provider’s interface.

Looker supports pull request integration for the following Git providers: GitHub, GitLab, Bitbucket Cloud, and Bitbucket Server (which was previously called “Stash”).

To set up your Looker project with Git pull requests:

1. From your project, select Project Settings from the Git drop-down menu.
2. In the Git Integration section, select Pull Requests Recommended or Pull Requests Required.
3. Copy the webhook information and paste it to a text file to use later in this procedure.
4. Optionally, click Set Webhook Secret to get a webhook deploy secret that authenticates your project’s Git integrations with your Git provider. Copy the deploy secret and paste it to a text file to use later in the procedure. See Webhook Deploy Secret for more information.
5. Click Save Project Settings.

Next, use your Git provider’s interface to create a trigger for the webhook:

5. Navigate to your project’s repository settings on your Git provider’s website.

TIP: Now that you’ve set up your project for Git integration, you can use the View Project on Git option from your project’s Git menu.

6. In your repository’s settings, click on Webhooks.
7. Click Add webhook. This will open the Add webhooks window.
8. In the Payload URL text box, paste the webhook information you copied from the Git Integration section in Looker.
9. Optionally, in the Secret text box, paste the webhook deploy secret you copied from the Webhook Deploy Secret section in Looker.
10. Select the option for Just the push event.
11. Click Add webhook.

And you’re set! Now, whenever a Looker developer commits changes to your project, the Looker IDE will show the Open Pull Request button. The button opens a new browser tab directly to the new pull request page on your Git provider’s website, and automatically fills in the title with the developer’s commit message from Looker:

Once the developer creates the pull request, the lead developer can approve it from the Git provider’s web interface, where the webhook will push changes to your Looker project’s production branch.

Some additional notes on using pull requests with Looker:

• If a developer has issued a pull request that you would like to revert, see this Community topic for information on reverting a pull request.

• Git pull requests can also be used to enable a staging instance for Looker, so you can have a staging instance and a production instance, with pull requests enabled on the staging instance. All development and code review can be done in the staging environment and the reviewed code can then be deployed to the production instance as desired. To set this up, see this Community topic.

• Looker merges changes from a developer branch into the production branch using the merge commit method of merging. When using your Git provider’s interface, be sure your developers do not use squash merging, nor rebase merging. See this section below for more information.

Merge Options in The Git Provider’s Interface

If your Looker project is integrated with pull requests, your developers use your Git provider’s interface to submit pull requests and merge changes into the production branch.

Looker supports the merge commit method of merging changes from a development branch into your production branch. However, your Git provider’s interface may show additional options for merging:

Looker does not support squash merging, nor rebase merging, so your developers should avoid using these options. If possible, the best practice is to disable the options for your repository. The following example shows disabling those options in a GitHub repo:

1. Navigate to your project’s repository settings on your Git provider’s website.

TIP: For projects configured with Git integration, you can use the View Project on Git option from the project’s Git menu in Looker.

2. In your repository’s settings, click Options.
3. Scroll down to the Merge button section.
4. Uncheck the Allow squash merging and Allow rebase merging options.

Once you uncheck these options, they won’t be available when merging a branch in the repository:

Webhook Deploy Secret

A webhook deploy endpoint prompts your Looker instance to pull the master branch of your project and deploy any changes in the master branch to the production version of your project. For most projects, the production branch and the master branch are one and the same, so you do not need the deploy webhook. However, for projects where the production branch is decoupled from the master branch, such as configurations with a staging instance used for testing, the deploy webhook pulls changes from the staging instance to the production instance.

Also, projects with Git pull request integration use the deploy webhook to push changes to production when a pull request is merged to master.

For these scenarios, you can add a secret for the deploy webhook so that your production version only updates when the webhook deploy secret is provided.

Adding a Deploy Secret

To add a webhook deploy secret to your project:

1. From your project, select Project Settings from the Git drop-down menu.
2. Scroll down to the Webhook Deploy Secret section, then click Set Webhook Secret. Looker will automatically generate a secret token. You can use this automatically generated secret, or you can type in your own secret token.
3. Whether you are using the automatically generated secret or creating your own secret, copy the webhook deploy secret and paste it to a text file so you’ll have it if you need to add the secret to the webhook for your repository. Be sure to copy it at this point. Once you leave or refresh the Project Settings page, you lose access to the webhook deploy secret and will have to change or remove the webhook deploy secret to regain access.
4. Click Save Project Settings.

The deploy webhook for your project now requires this secret. For projects that use a Looker staging instance, you need to include the webhook deploy secret in your HTTP header in order to deploy to production. For projects with Git pull request integration, you need to go to your Git provider’s interface to add the secret to the webhook for your repository.

Configuring the Secret for Your Git Repository’s Webhook

For projects with Git pull request integration, if you have added a deploy webhook secret to your LookML project, you need to go to your Git provider’s interface to add the secret to the webhook for your repository. As an example, here is how you do that using GitHub:

1. Navigate to your project’s repository settings on your Git provider’s website.

TIP: If you’ve set up your project for Git integration, you can use the View Project on Git option from your project’s Git menu in Looker.

2. In your repository’s settings, click on Webhooks.
3. Find the webhook for your LookML project, then click its Edit button.
4. In the Secret text box, paste the webhook deploy secret you copied from the Webhook Deploy Secret section in Looker.
5. Click Update webhook.

The webhook secret is now required in order to deploy changes to the production version of your project. If you need, you can change the secret or remove the secret from your project.

Changing a Deploy Secret

Once a webhook deploy secret has been added to your project, you can change the secret by doing the following:

1. From your project, select Project Settings from the Git drop-down menu.
2. Scroll down to the Webhook Deploy Secret section and click Reset Secret. Looker will automatically generate a new secret token. You can use this automatically generated secret, or you can type in your own new secret token.

3. Whether you are using the automatically generated secret or creating your own secret, copy the webhook deploy secret and paste it into a text file so you’ll have it if you need to add the secret to the webhook for your repository. Be sure to copy it from your clipboard at this point. Once you leave or refresh the Project Settings page, you will lose access to the webhook deploy secret and will have to go back and change it or remove it entirely.

4. Click Save Project Settings.

If your project is configured with Git pull request integration, you also need to go to your Git provider’s interface to update the webhook secret for your repository.

Removing a Deploy Secret

Once a webhook deploy secret has been added to your project, you can remove the secret by doing the following:

1. From your project, select Project Settings from the Git drop-down menu.
2. Scroll down to the Webhook Deploy Secret section and click Remove Secret. At this point, you can cancel the operation and keep the deploy secret by clicking Don’t Remove.
3. To permanently remove the webhook deploy secret from your project, click Save Project Settings.

Your project no longer requires a secret for the deploy webhook. If your project is configured with Git pull request integration, you can now go to your Git provider’s interface to remove the webhook secret from your repository. Looker itself will no longer check for a secret on the Git provider’s end, so it doesn’t hurt if your Git repo webhook still has a secret configured. If you do want to remove the secret from your Git repository, see Configuring the Secret for Your Git Repository’s Webhook for information on editing the secret on a Git provider’s interface.