This page describes how to configure elements of your project to integrate with Git for version control.
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: 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 upgrade.
- 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.
- 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 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 this Help Center article.
On the Branch Management tab of the Projects Settings page, you can see all the Git branches associated with the project.
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 the Using Version Control and Deploying 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 the Integrating Pull Requests for Your Project 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, Looker 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:
- From your project, select Project Settings from the Git drop-down menu.
- In the Git Integration section, select Pull Requests Recommended or Pull Requests Required.
- Copy the webhook information and paste it to a text file to use later in this procedure.
- 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.
- Click Save Project Settings.
Next, use your Git provider’s interface to create a trigger for the webhook:
- Navigate to your project’s repository settings on your Git provider’s website.
- In your repository’s settings, click on Webhooks.
- Click Add webhook. This will open the Add webhooks window.
- In the Payload URL text box, paste the webhook information you copied from the Git Integration section in Looker.
- Optionally, in the Secret text box, paste the webhook deploy secret you copied from the Webhook Deploy Secret section in Looker.
- Select the option for Just the push event.
- 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 Looker 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 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 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 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 Merge Options in the it Provider’s Interface section 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 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.
- 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: