home User Guide Getting Started Help Center Documentation Community Training Certification
menu
close
settings
Looker keyboard_arrow_down
language keyboard_arrow_down
English
Français
Deutsch
日本語
search
print
Configuring project version control settings

This page describes how to configure elements of your project to integrate with Git for version control.

Project settings

You must be a Looker admin to change options on the Project Settings page. Looker developers who are not admins can view the Project Settings page but cannot change the options there.

The Project Settings page has configuration options for your project. To see this page, open your project and select the Settings icon from the left-hand icon menu:

From here you can access three sections, described below:

Configuration

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

Git production branch name

With the default Looker Git integration, all Looker developers merge their changes into a branch called master. You can use the Git Production Branch Name field to specify which branch from your Git repository that Looker should use as the target branch into which your Looker developers’ branches are merged. (See the Using version control and deploying documentation page for the default Git workflow and other options for advanced Git implementations.)

For existing projects, consider doing the following before changing the Git production branch name:

To change the Git branch that your project uses as the merge target for development branches:

  1. Navigate to the Configuration tab of the Project Settings page by clicking the Settings icon from the left-hand icon menu.
  2. In the Git Production Branch Name field, enter the name of the Git branch you want to use as the production branch for your Looker project.
  3. Scroll down and click the Save Project Configuration button to save your change.

Import Credentials

The Import Credentials section is where you can manage authentication credentials for private remote repositories. See the Importing files from other projects documentation page for details.

Branch Management

On the Branch Management tab of the Projects Settings page, you can see all the Git branches associated with the project. See the Using version control and deploying documentation page for details.

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 the Using version control and deploying documentation page. That’s all you need to do to set up your project with source file management and version control. However, if you are a Looker admin, you can configure additional options for Looker’s integration with Git using the Git Integration options on the Configuration tab of the Project Settings page.

When Git Integration is set to 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.

The following options apply only if you are self-hosting your repository using a Git provider, as described in the Integrating Looker with Git section of the Setting up and testing a Git connection documentation page. To see if your Git repository is Looker-hosted, scroll to the bottom of the Branch Management tab of the Project Settings page to see the Remote Origin URL. Looker-hosted repos have a URL starting with git@github.com:llooker.

If you switch Git integration on or off, scroll down and click Save Project Configuration under the Deployment section to save your change.

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 three-dot menu for each of your LookML files, Looker provides links to your Git provider’s site to view the file, to view the Git blame information for the file, and to view the commit history for the file:

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

Integrating pull requests for your project

With the default Looker Git integration, Looker developers commit their changes to their development branch, then merge their development branch into the production branch. Then, when you deploy to the Looker environment, Looker uses the latest commit on the production branch. (See the Using version control and deploying documentation page for the default Git workflow and other options for advanced Git implementations.)

Instead of allowing Looker developers to merge their development branch into the Looker production branch, you can set up your project with either the Pull Requests Recommended or the Pull Requests Required option:

Looker supports pull request integration for the following Git providers:

Here are some additional notes on using pull requests with Looker:

Setting up your project with integrated pull requests

To set up your Looker project with Git pull requests:

  1. From your project, select Project Settings from the left-hand icon menu.
  2. In the Git Integration section of the Configuration tab, select Pull Requests Recommended or Pull Requests Required.
  3. Optionally, if you want to set up an automatic deploy webhook on your Git provider’s interface, copy the webhook information and paste it into a text file. If your project is configured to use advanced deploy mode, you can skip this step. You can also decide later and come back to the project settings to get the webhook information.
  4. Optionally, you can set up a webhook deploy secret to authenticate an automatic deploy webhook from your Git provider or an advanced deploy mode webhook. To create a webhook secret, click Set Webhook Secret. Copy the deploy secret and paste it into a text file to use when you add the webhook to your Git provider’s interface. You can also decide later and come back to the project settings to add a deploy secret. See the Configuring the webhook deploy secret documentation page for more information.
  5. Click Save Project Configuration.

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:

Once you have set up your Looker project to use pull requests, do one of the following to set up how commits are deployed to your production environment:

Adding a webhook to your Git provider

For Looker projects enabled for pull requests, you can set up a deploy webhook on your Git provider’s interface. This webhook will trigger Looker to deploy the latest commit from the production branch whenever you merge a pull request on the Git provider’s interface.

In most cases, you don’t want to set up an automatic deployment webhook if your project is configured to use advanced deploy mode. Advanced deploy mode allows you to select the commit and branch that you want to deploy, so in most cases setting up an automatic deploy webhook would nullify the features of advanced deploy mode.

To add an automatic deploy webhook on your Git provider’s interface, first go to your project settings in Looker and copy the webhook from the Git Integration section:

In this example, the webhook information is <host_url>/webhooks/projects/e_faa/deploy

Replace the <host_url> with the URL for your Looker instance. For example:

https://docsexamples.dev.looker.com/webhooks/projects/e_faa/deploy

From the Looker project settings, you can also get a webhook deploy secret to authenticate your project’s Git integrations with your Git provider. See the Configuring the webhook deploy secret documentation page for more information.

Once you have the webhook URL and the deploy webhook secret, you can enter them into your Git provider’s interface. Here is an example using GitHub as the Git provider:

  1. Navigate to your project’s repository settings on your Git provider’s website.
  2. In your repository’s settings, click on Webhooks. Click Add Webhook to open the Add Webhook window.
  3. In the Payload URL text box, paste the webhook information you copied from the Git Integration section in Looker.
  4. Optionally, you can add a webhook deploy secret that authenticates your project’s Git integrations with your Git provider. Copy the deploy secret from the project settings of your LookML project and paste the secret into the Secret text box in the Git provider’s interface. See the Configuring the webhook deploy secret documentation page for more information.
  5. Select the option for Just the push event.
  6. Click Add webhook.

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 or 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.

  1. In your repository’s settings, click Options.

  2. Scroll down to the Merge button section and leave checked only the Allow merge commits option. 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:

Top