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
Using Version Control and Deploying

This page assumes that your project has already been set up for version control. If you see a Configure Git button instead of the choices described on this page, you need to first set up Git for your project.

Git Integration for Version Control

Looker uses Git to record changes and manage file versions. Each LookML project corresponds with a Git repository, and each developer branch correlates to a Git branch. Git repositories are often called repos.

Looker generally uses GitHub for LookML source-file management. However, Looker can be configured to also work with other Git providers such as GitLab, Bitbucket, or any Git server that can use an SSH key for authentication.

A Looker project uses only one account with your Git provider for all Git interactions (see the Integrating Looker with Git documentation page for information on setting up Git). For each Looker project, all of the development from all of your Looker developers goes through this one Git account. This means that Looker developers do not need to have their own accounts with your Git provider, unless your Looker instance is set up with one of the additional Git integration options. In this case, a Looker developer would need a Git account to open external links to your Git provider or to create a pull request.

Working with Git Branches

One of the main benefits of Git is that a Looker developer can work in a branch, an isolated version of a file repository. You can develop and test without affecting other users. As a developer in Looker, you are using a Git branch whenever you are in Development Mode.

Another major feature of Git is the ease of collaborating with other developers that it provides. You can create a branch and (if desired) make changes, and then other developers can switch to that branch to review or make changes to the branch. If another developer has committed changes to the branch, Looker displays the Pull Remote Changes button. You should pull those committed changes to the branch before making additional changes.

You can also delete a branch other than the master branch, your current branch, or a developer’s personal branch.

Personal Branches

The first time you go into Development Mode, Looker automatically creates your personal Git branch. Your personal branch starts with dev- and includes your name:

Your personal branch is specific to you, and it cannot be deleted. In addition, your personal branch is read-only to all other developers. Keep this in mind if you are collaborating with other developers on a project. Instead of using your personal branch to work on the project, you may want to create a new branch so that others can switch to the branch and contribute changes as well.

TIP: You can’t make changes to another developer’s personal branch. So, if you want to build on work in somebody else’s personal branch, create a new branch starting from their branch.

Creating a New Git Branch

If you are working on a simple fix and not collaborating with other developers, your personal branch is usually a good place to work. You can use your personal branch to make quick updates, and then commit the changes and push them to production.

However, you may also want to create new Git branches in addition to your personal branch. A new Git branch makes sense in these situations:

Before creating a new branch:

To create a new Git branch:

  1. Verify that you have Development Mode turned on.
  2. Navigate to your project in the Develop menu.
  3. In the project, navigate to the Git Actions panel by clicking the Git icon in the left-hand icon menu.
  4. In the Git Actions panel, select New Branch from the Git branch drop-down menu. This opens the New Branch window.
  5. In the New Branch window, enter a name for your branch. Note that there are limitations for Git branch names; for naming requirements, see Rules for Naming a Git Branch, below.
  6. Click the Create From drop-down menu and select an existing branch to use as the starting point for your new branch.
  7. Click Create to create your branch.

Alternatively, you can create Git branches from the Branch Management tab of the Project Settings page.

Rules for Naming a Git Branch

Looker uses the branch-naming-convention requirements specified by Git.

Git branch names must not:

In addition, the branch name can only contain an asterisk (*) if the asterisk represents an entire path component (for example, foo/* or bar/*/baz), in which case it is interpreted as a wildcard and not as part of the actual branch name.

Switching to Another Git Branch

If you have a merge conflict on your current branch, you must resolve the conflict before you can switch to a different branch.

Also, if you have uncommitted changes on your current branch, you cannot switch to an existing branch. You can, however, create a new branch from your current branch. When you create a new branch, any uncommitted changes will follow you so you can commit the changes in the new branch.

To switch to a different Git branch:

  1. In the project, navigate to the Git Actions panel by clicking the Git icon in the left-hand icon menu.
  2. In the Git Actions panel, click on the Git branch drop-down menu by your current Git branch name.
  3. Select the branch you want to switch to by selecting it in the menu, or by typing the branch name into the search box. Branch name search is case-insensitive. For example, you can search for “DEV” and see all branches with names that include “dev”, “DEV”, “Dev”, and so on.

Managing Git Branches

The Branch Management tab of the Project Settings page shows a table of all the Git branches for the Looker project. To open the Branch Management tab, navigate to the Project Settings page by clicking the Settings icon from the left-hand icon menu and selecting the Branch Management tab.

On the Branch Management tab, you can:

  1. Create a new branch by clicking the New Branch button. See the Creating a New Git Branch section of this page for more information.
  2. Search for branch names in the Search Bar.
  3. Refresh the table by clicking the Refresh button.
  4. Sort the table by clicking a column name.

The table includes the following information:

Deleting Git Branches

From the Branch Management tab, you can delete branches that have a Delete button in the table. You cannot delete the following branches:

In the table, these branches don’t have a Delete button. Instead, the Action column of the table shows the reason that the branch can’t be deleted.

You cannot restore a branch once it’s been deleted. When you delete a branch, Looker removes both your local version of the branch and the remote version of the branch.

However, if the branch was created by another Looker developer, or if other developers have checked out the branch, those developers will still have their local version of the branch. If a Looker developer makes commits to their local version of the branch and pushes it to production, you will once again see a remote version of the branch. This can be handy if you do want to restore the branch. Otherwise, when you delete a branch, all other Looker developers should delete the same branch to ensure that it can’t be accidentally resurfaced by someone pushing it to remote.

To delete one or several Git branches from your project:

  1. In the project, navigate to the Project Settings page by clicking the Settings icon from the left-hand icon menu.
  2. Select the Branch Management tab.
  3. To delete branches in bulk, use the checkboxes to select one or more branches and then click Delete Selected Branches.
  4. To delete a single branch, click the Delete button next to the branch name to delete that single branch.

Executing Git Commands in Looker

Looker has a built-in interface that integrates with your Git service. In the LookML IDE, you’ll see a button in the upper right for Git:

The Git button shows different options depending on where you are in the process of making changes and deploying to production. In general, the option shown on the button is the best guide for your next action.

If your developer branch is in sync with the production branch, you will see the Up-to-Date with Production message:

Once your project is configured for Git, the IDE will show the Git Actions panel with additional Git commands:

The commands available on the Git Actions panel depend on where you are in the process of making changes and deploying to production. For example, these options and prompts are available after you validate a change and before you commit:

These options and prompts are available after you make a commit, before you deploy to production:

Getting Your Changes to Production

To give business users access to your changes, you need to commit the changes and then deploy to production. Before committing, you may want to first review the uncommitted changes.

If you see a Configure Git button instead of the choices described in this section, you need to first set up Git for your project.

Viewing Uncommitted Changes

The LookML IDE has several indicators that are displayed when you are in Development Mode and have uncommitted changes, as described in the Marking Additions, Changes, and Deletions section of the Editing and Validating LookML documentation page.

You can also get a difference summary for all files by using the View Uncommitted Changes option from the Git Actions panel:

In the Uncommitted Changes to Project window, you can see a summary of all of the uncommitted, saved changes in all of the project’s files. For each change, Looker shows the following:

  1. The name of the replaced file and the name of the added file.
    • The name of the replaced file (indicated with ---) and the name of the added file (indicated with +++). In many cases, this may show different versions of the same file, with revisions identified by --- a/ and +++ b/.
    • Deleted files are shown as replacing a null file (+++ /dev/null).
    • Added files are shown as replacing a null file (--- /dev/null).
  2. The line number where the change begins.
    For example, -101,4 +101,4 indicates that, at the 101st line in the file, 4 lines were removed and 4 lines were added. A deleted file with 20 lines would show -1,20 +0,0 to indicate that, at the first line in the file, 20 lines were removed and replaced by zero lines.
  3. The text that was updated:
    • Deleted lines are displayed in red.
    • Added lines are displayed in green.

You can also get a difference summary for a single file by selecting the View Changes option from the file’s menu:

Committing Changes

After you have made and saved any changes to your LookML project, the IDE may require you to validate your LookML:

Whether this is required depends on your project’s setting for code quality. For more information on the Content Validator, see the Validating Your LookML documentation page.

If another developer has made changes to the production branch since you last updated your local branch, Looker requires you to pull those updates from the production branch:

Once you save your changes (and fix any LookML warnings or errors, if required) and pull from production (if required), the Git button displays the following message:

If desired, you can first review your uncommitted changes before committing.

When you are ready to commit the changes, use the Commit Changes & Push button to commit these changes to your current branch. The following window appears, listing the files that have been added, changed, or deleted.

Enter a message that briefly describes your changes, and uncheck any files you don’t want included in the sync. Then click Commit to commit the changes.

Running Data Tests

Your project may include data tests to verify the logic of your LookML model. See the test documentation page for information on setting up data tests in your project.

You must be in Development Mode to run data tests. Once you’re in Development Mode, there are several ways to initiate data tests for a project:

  1. If your project settings are configured to require data tests to pass before deploying production, the IDE will present the Run Tests button after you commit changes to the project. This will run all the tests for your project, no matter which file defines the test. You must pass the data tests before you can deploy your changes to production.
  2. Click the Run Data Tests icon in the Code Validation tab. This will run all data tests in your project, no matter which file defines the test.
  3. Select the Run LookML Tests option from the file’s menu. This will run only the tests defined in the current file.
  4. Once you run the data tests, the IDE will show you the progress and results.
    • A data test passes when the test’s assertion is true for every row in the test’s query. See the test documentation page for details on setting up test assertions and queries.
    • If a data test fails, the data test window will provide information about why the test failed, whether the test found errors in your model’s logic or if it was the test itself that was invalid.
    • From the data test results, you can click on the name of a data test to go directly to the LookML for the data test, or you can click on the Explore Query button to open an Explore with the query defined in the data test.

Deploying to Production

Once you have committed changes to your project, the IDE will display the Merge & Deploy to Prod button so that you can push your committed changes to production for other users to see.

If your project is configured for Git integration using pull requests, you will see the Open Pull Request button instead of the Merge & Deploy to Prod button. The Open Pull Request 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.

Advanced Deploy Mode

When enabled, Advanced Deploy Mode allows developers to deploy any commit to production, instead of only the leading commit, or “head,” of the master branch. This helps consolidate repositories in multi-environment developer workflows, where each environment points to a different version of a codebase. It also gives greater control to one or a few developers or administrators over the changes that are deployed to production.

Changes are deployed to production either by webhook, or through the API.

Enabling Advanced Deploy Mode

To enable advanced deploy mode:

  1. Navigate to the Configuration tab of the Project Settings page by clicking the Settings icon from the left-hand icon menu.
  2. Click the checkbox next to Enable Advanced Deploy Mode, under the Git Integration section.
  3. Click the Save Project Settings button to save the setting.

Version Control with Advanced Deploy Mode

When advanced deploy mode is enabled, deploying to production from the UI is no longer an option for developers. After making a commit, the IDE will prompt users to Merge to Master, instead of Merge & Deploy to Prod:

The IDE also displays a message warning users that their changes can only be deployed through the deploy endpoint.

Changes are deployed to production either with a webhook, or through the API, as described next.

Deploying with Webhooks

Two webhooks are available for deploying changes to production with advanced deploy mode enabled. One webhook is for deploying the head of a branch, and the other is for deploying a specific Git SHA or tag:

When you trigger or add the webhook URL in the following steps, be sure to replace the information in the angle brackets < > with the information specific to your instance address, LookML project, branch name, SHA, or tag.

To set up the deploy webhook, you must first set a webhook secret for your Looker project from the Configuration tab in the Project Settings page. This is to ensure that only authorized parties can trigger the deploy webhook.

Once the webhook secret is set, it can be triggered to deploy. The most common use case for triggering a webhook is through your Git hosting provider, such as GitHub. The following steps outline how to add the webhook secret and deploy webhook to the project repository settings in GitHub:

  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 desired webhook URL to deploy either the head of a branch or a specific commit SHA or tag.
  4. Input the webhook deploy secret from the Webhook Deploy Secret section in Looker into the Secret text box.
  5. Select the option for Just the push event.
  6. Click Add webhook.

The webhook URL may need to be updated according to the desired changes being pushed. To change the webhook URL, find the webhook for your LookML project settings on your Git provider’s website, and then click the webhook’s Edit button. Change the Payload URL and click Update Webhook.

Deploying with the API

Deploying with the Looker API is an alternative to deploying with a webhook when advanced deploy mode is enabled. To deploy with the API, the API user making the call will need deploy permissions.

See the Looker API Authentication and Getting Started with the API documentation pages for more information about authenticating and using the Looker API.

To deploy with the API, use the deploy_remote_branch_or_ref_to_production endpoint. This endpoint can be called in several different ways. The following examples are for the HTTPs and SDK methods.

HTTPS

When you’re using the following examples, be sure to replace the information in the angle brackets < > with the information specific to your instance address, LookML project, branch name, SHA, or tag.

To manually deploy via the deploy_remote_branch_or_ref_to_production API endpoint, see the following examples using the HTTPs method. For more information and examples of manually calling the API via CURL requests, see the How to Authenticate to the API GitHub readme, or use the interactive API documentation in the admin panel.

Use the following examples in an HTTPs request to deploy either the head of a branch or specific commit SHA or tag via the deploy_remote_branch_or_ref_to_production API endpoint:

Deploy the head of a branch: <HOST_URL>/api/3.1/projects/<PROJECT_ID>/deploy_ref_to_production?branch=<BRANCH_NAME>

Deploy a commit SHA or tag: <HOST_URL>/api/3.1/projects/<PROJECT_ID>/deploy_ref_to_production?ref=<SHA_OR_TAG>

SDK

When you’re using the following examples, be sure to replace the information in the angle brackets < > with the information specific to your LookML project, and branch name, SHA, or tag.

Alternatively, use one of Looker’s SDKs instead of making manual requests to the API. SDKs handle the details of authentication, parameter and response serialization, and other concerns.

Deploying with the deploy_remote_branch_or_ref_to_production with the SDK method looks like the following:

Deploy the head of a branch: deploy_ref_to_production(<PROJECT_ID>, {branch: <BRANCH_NAME>})

Deploy a commit SHA or tag: deploy_ref_to_production(<PROJECT_ID>, {ref: <SHA_OR_TAG>})

Checking the Impact of Your Changes

After making your changes available to the organization, you can use content validation to make sure you have not invalidated any dashboards or saved Looks. You’ll have the opportunity to fix them if you have.

Handling Typical Issues

While working on your model, you may need to:

Some changes, such as changing the name of a field, can affect existing dashboards and Looks. As mentioned earlier, after making your changes available to the organization, you can use content validation to check your content and fix any issues.

Reverting Uncommitted Changes

If you do not want to deploy your saved changes, you can revert all the uncommitted changes for all files in the project or just text changes in a single file.

To revert uncommitted changes for all files:

  1. Click the Revert to… option in the Git Actions panel.
  2. Select a revert option:
    • To revert only uncommitted changes, select Revert uncommitted changes. You can also click the View changes link to view the changes that would be reverted.
    • To revert all changes, including uncommitted and committed changes, select Revert to Production
  3. To complete the revert, click Confirm.

To revert any additions or deletions in the contents of a single file, select the Revert Changes option from the file’s menu:

When you rename a file, you are essentially deleting the original file and creating a new file with a new name. Because this involves more than one file, you can’t use the Revert File option to undo the renaming of a file. If you want to undo a file rename, use the Revert to… option from the Git Actions panel.

Also, if you have deleted a file, the file is no longer displayed in the IDE file browser. If you want to revert the deletion of a file, use the Revert to… option from the Git Actions panel.

Resolving Merge Conflicts

Typically, Git can automatically merge your new changes with the production version of your LookML files. A merge conflict occurs when Git has trouble determining which changes to keep. This usually occurs when another developer has made changes since you last pulled and you have made changes in the same area. If you have a merge conflict in your code, you will be warned in Looker after you commit changes and pull from production:

When Looker shows the merge-conflict warning, it is crucial that you do not push any further changes until you have resolved the merge conflict. Pushing a merge conflict to production will cause parse errors that may prevent exploration of your data. If you would like to move forward with pushing changes, click the Don’t Resolve button.

In the LookML file itself, the lines with conflicts are marked like this:

Looker shows the following merge markers to indicate the merge conflicts:

In the example above, your code represents the changes you committed, and production code represents the code into which Git could not automatically merge your changes.

To resolve a merge conflict:

  1. Find the files with merge conflicts. Looker marks these files in red, or you can also search your project for merge markers, such as <<<< or HEAD, to find all the conflicts in your project. You can also find impacted files by clicking the files link in the merge warning that appears in the Git Actions panel.
  2. In the file, go to the lines with merge conflicts and delete the version of the text that you do NOT want to keep, and also delete all the merge conflict markers.
  3. Save the file, and repeat the above steps for any other files marked with merge conflicts.

TIP: Search your project for each of the merge markers to verify that you have resolved all conflicts and deleted all the merge markers. Make sure to remove all instances of merge markers in your LookML files. These markers will cause parse errors that can prevent users from exploring your data.

  1. After you have resolved all merge conflicts and deleted all merge markers from your project, click on Commit & Resolve Conflict to commit your changes.
  2. Enter a commit message to describe your changes.
  3. Click Commit to commit your merge-conflict resolution.
  4. Click Merge & Deploy to Prod to push all your changes to production.

Now that you have resolved the merge conflict and pushed your resolution to production, other developers can pull from production and continue work as usual.

Git Garbage Collection

Git garbage collection cleans up unnecessary files and compresses file revisions to optimize your Git repository. Git garbage collection (git gc) is run automatically when your Looker instance is updated or rebooted. To keep from running git gc too often, Looker waits 30 days since the last git gc and then runs git gc on the next reboot.

In rare cases, you might try to Push Changes to Remote or Push Branch to Remote while git gc is running. If Looker displays an error, wait for a minute or two and then try again to push your changes.

Top