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:

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

If IP Allowlisting is enabled on your instance, to integrate pull requests with any LookML projects you will need to allowlist the range of IP addresses from which your Git provider makes outbound requests. For example, current Github IP addresses are listed in the Github changelog. IPs are subject to change and will be different for other Git providers.

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 the Migrating to a New Git Repository Help Center article for information about migrating to a new Git repository, such as from a Looker-hosted repository to a self-hosted repository.

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

With either Pull Requests Recommended or Pull Requests Required, Looker developers submit a Git pull request for the changes on their branch. Once the developer creates the pull request, the other Looker developers can review and 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:

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 that authenticates your automatic deploy webhook from your Git provider. 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. Again, 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 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.

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