+1 (726) 227-2971
Vistelio

Looker Git Workflow in Practice: Branches, Pull Requests, Advanced Deploy Mode, and Deploy Webhooks

Most Looker projects are version controlled in name only. The repository exists, every developer has a personal branch, and the deploy story is "whoever finishes last presses Deploy to Production." That works until the instance has more than two developers, a business-critical dashboard, or an auditor who wants to know who changed a revenue definition and when.

This tutorial walks through the Git workflow we set up on client instances: how branches should be organised, how pull requests fit around LookML validation, what Advanced Deploy Mode actually changes, and how deploy webhooks let a CI pipeline own production. It assumes you already have a Looker project connected to GitHub, GitLab, Bitbucket or Azure DevOps.

1. How Looker's Git model differs from a normal repo

Two things surprise developers coming from software engineering:

  1. Every developer gets a personal branch automatically. When you enter Development Mode, Looker checks out dev-firstname-lastname-xxxx for you. It is a real Git branch, pushed to the remote, and it is yours alone.
  2. Production is a pointer, not a branch you push to. By default, production serves the tip of your production branch (usually main or master). "Deploy to Production" means: merge my branch into the production branch and move the instance's production HEAD to it.

So Looker already gives you feature isolation. What it does not give you by default is a review gate between a developer's branch and what your business users see. That gate is the part you have to build.

2. A branching strategy that survives more than one developer

Keep it boring:

  • main — the production branch. Protected. No direct pushes.
  • dev-<name>-<id> — Looker's auto-created personal branches. Short lived, rebased or reset often.
  • feature/<ticket>-<slug> — optional named branches for work that needs to be shared between two developers or parked across sprints. Create these from the Git menu with Create New Branch and set the base to main.

Two rules matter more than the naming:

Rule 1: pull from production before you start, and before you commit. The Git menu in Development Mode shows "Pull from Production" whenever main has moved ahead of you. Skipping it is how you get merge conflicts inside .model.lkml files, which are painful to resolve in the browser IDE.

Rule 2: one logical change per branch. LookML diffs are read by humans. A branch that renames a dimension, adds an Explore and reformats three views is a branch nobody reviews properly.

3. Turn on pull requests

In Project Settings → Version Control, set Pull Request Required. When it is on, the Deploy button in the IDE is replaced with an Open Pull Request action that sends the developer to the Git provider with the branch pre-selected.

On the provider side, protect main:

  • Require at least one approving review.
  • Require status checks to pass (this is where your LookML CI hangs — see the companion tutorial on data tests, LAMS and Spectacles).
  • Disallow force pushes and direct commits.

With those two halves in place, the only route from a developer's laptop to a business dashboard runs through a reviewed, tested pull request. That single change removes the majority of "who broke the revenue tile?" incidents we get called in for.

A practical detail: Looker's IDE will still let a developer commit to their personal branch freely. Reviews happen on the PR, not on the commit, so encourage small, frequent commits with meaningful messages. The commit message is the only context a reviewer gets for a LookML change six months later.

4. What Advanced Deploy Mode actually gives you

Standard deployment moves production to whatever the merge produced, immediately, on the developer's click. Advanced Deploy Mode (enabled per project in Project Settings) changes three things:

  1. Deployment becomes a separate, permissioned action. Only users with the deploy permission can move production. Developers can merge all day without touching what end users see.
  2. You get a deployment history. The Deployment Manager lists past commits with author, message and timestamp — the audit trail your governance team keeps asking for.
  3. You can roll back by selecting an earlier commit. Production HEAD moves back to that commit in seconds. No revert commit, no scramble.

The operational shape becomes: developers merge to main continuously; a release owner (or a pipeline) promotes main to production on a schedule — daily, or after the nightly PDT rebuild window, or whenever the release checklist is signed off.

One caveat worth planning for: PDTs and datagroups. Deploying a change that alters the SQL of a persistent derived table triggers a rebuild. If your rebuild takes 40 minutes, deploy before the business day, not during it.

5. Deploy webhooks: letting CI own production

If you want promotion fully automated, Looker exposes a deploy endpoint per project:

POST https://<your-instance>/webhooks/projects/<project_name>/deploy

Authenticate with the project's Git deploy secret in the X-Looker-Deploy-Secret header (set it in Project Settings → Deploy Secret), or call the equivalent SDK method with an API key:

curl -X POST \
  -H "X-Looker-Deploy-Secret: $LOOKER_DEPLOY_SECRET" \
  "https://your-instance.cloud.looker.com/webhooks/projects/ecommerce/deploy"

With the SDK (Python, API 4.0):

import looker_sdk

sdk = looker_sdk.init40()
sdk.deploy_ref_to_production(project_id="ecommerce", branch="main")

Wire that into the main branch job of your CI provider, after the LookML validator and data tests pass. The full pipeline then reads:

  1. Developer opens a PR from their Looker branch.
  2. CI runs LookML validation, LAMS style rules, Spectacles SQL and content validation against the branch.
  3. A reviewer approves; the PR merges into main.
  4. The main job re-validates and calls the deploy webhook.
  5. Advanced Deploy Mode records the commit in the deployment history.

Store the deploy secret in your CI secret manager, never in the repository, and rotate it when a developer with access leaves.

6. Multi-instance and multi-project setups

Larger clients run separate dev, QA and production instances, not just Development Mode. The pattern that works:

  • All instances point at the same Git repository, different branches. Dev instance tracks main; production instance tracks a release branch (set the production branch per project in Project Settings).
  • Promotion is a fast-forward merge from main into release, followed by a deploy webhook call against the production instance.
  • Connection names stay identical across instances; the underlying database each connection points to differs. That way no LookML has to change between environments.
  • Use include and refinements rather than environment-specific forks of a view file. If you find yourself commenting out blocks per environment, reach for user attributes on the connection instead.

For remote dependencies (shared LookML across projects via manifest.lkml), pin the ref to a tag or commit SHA rather than a branch. A floating ref: "main" on a shared project means someone else's merge can change your production model without a deploy on your side.

7. Cleaning up

Stale branches accumulate fast — Looker creates one per developer per project, and named feature branches linger. Once a quarter:

  • Delete merged feature/* branches at the provider.
  • Have developers reset their personal branch to production (Git menu → Reset to Remote) so nobody is carrying six months of drift.
  • Review who holds the deploy permission and the Git deploy secret.

Checklist

  • main is protected: no direct pushes, review required, status checks required.
  • Pull Request Required is on in Project Settings.
  • Advanced Deploy Mode is on, and deploy is granted to a small group.
  • CI validates LookML on every PR and calls the deploy webhook on main.
  • Deploy secret lives in a secret manager and is rotated on team changes.
  • Remote LookML dependencies are pinned to tags or SHAs.
  • Stale branches are cleaned up on a schedule.

Getting help with the setup

Retrofitting a Git workflow onto a live Looker instance is mostly a sequencing problem: you have to introduce the gate without stalling the developers who are mid-project, and without breaking the PDT rebuild schedule. Vistelio's senior Looker developers do this regularly as part of a health check or an ongoing development engagement. If your team is deploying straight to production today and would like a reviewed, auditable pipeline instead, get in touch and describe your setup — instance count, team size and Git provider are enough for us to sketch a plan.