This page describes how to configure elements of your project to integrate with Git for version control.
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:
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 Configuration button. See the Accessing and Editing Project Information documentation 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: Looker 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: Looker 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 update.
- Allow committing broken code: Looker 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.
Require data tests to pass before deploying this project to production: Requires developers to run data tests before deploying any changes. If the data tests pass, the IDE will allow the developer to deploy changes to production. See the
testdocumentation page for information on setting up data tests in your LookML project. See the Using Version Control and Deploying documentation page for information on running data tests on your project.
Git Integration: Specifies the levels of integration with your Git provider. See Git Integration Options for details.
- Enable Advanced Deploy Mode: A setting that, when enabled, allows users to deploy any SHA, tag, or branch to production. See the Advanced deploy mode documentation page for more information about using version control with Advanced Deploy Mode enabled.
- Webhook Deploy Secret: Sets up authentication for deploying changes to production on your Looker instance. See the Configuring the Webhook Deploy Secret documentation page for details.
Reset Git Connection: This button opens the Configure Git window, where you can update the connection settings for your Git repository.
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 sync their dev mode. To preserve history for all branches, see the Migrating to a New Git Repository Help Center article.
Delete Project: This button deletes the project, removing all LookML from the project in all development and production environments across your Looker instance.
- Git Summary: This section shows the project’s Git configuration and the current user’s Git branch information.
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.
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
- 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. Looker will also 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. If you have a Looker-hosted Git repository, the Show Links option has no effect.
- 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 the Integrating Pull Requests for Your Project section for information on setting this up. If you have a Looker-hosted Git repository, you will not see this option.
- 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. If you have a Looker-hosted Git repository, you will not see this option.
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:
If you have enabled advanced deploy mode, it is not necessary to configure a webhook in the Setting Up Your Project with Integrated Pull Requests section, since advanced deploy mode separates the merge and deployment functions.
If a Looker 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 make it possible to use 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 the Git Workflow Using One Repository Across Multiple Instances — Development, Staging, and Production Help Center article.
Looker merges changes from a Looker 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 the Merge Options in the Git Provider’s Interface section for more information.
Setting Up Your Project with Integrated Pull Requests
To set up your Looker project with Git pull requests:
- From your project, select Project Settings from the left-hand icon menu.
- In the Git Integration section of the Configuration tab, select Pull Requests Recommended or Pull Requests Required.
- 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.
- 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.
- 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:
- To automatically deploy the latest commits that are merged to your production branch, use your Git provider’s interface to add a webhook, as described in the next section on this page.
- To manually specify which branches or commits are deployed, enable advanced deploy mode. See the Advanced deploy mode documentation page for information on enabling and managing advanced deploy mode.
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> with the URL for your Looker instance. For example:
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:
- Navigate to your project’s repository settings on your Git provider’s website.
- In your repository’s settings, click on Webhooks. Click Add Webhook to open the Add Webhook window.
- In the Payload URL text box, paste the webhook information you copied from the Git Integration section in Looker.
- 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.
- Select the option for Just the push event.
- 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:
- 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.
In your repository’s settings, click Options.
- 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: