Metaplane uses Looker's API to extract information about all your Looker Explores, Dashboards, and more. However, the API is somewhat limited in the information it exposes, resulting in gaps in your Looker lineage tree that are an unavoidable result of these API limitations. In order to build a significantly more powerful and complete view of your Looker projects, Metaplane is now able parse the LookML code that defines your Looker projects directly. In order to do this, some additional steps are needed to give Metaplane read access to the Git repositories where your LookML code is stored.

Identifying your LookML Git repositories

For ease of setup, you can view the list of all your Git-enabled LookML projects and their remote repository URLs in Metaplane. Just navigate to your Looker connection page, and click the Edit Git configuration button in the top-right corner.

You'll see a list of LookML projects like this:

We can see that there's a project called metaplane, and below it is the repository URL and production branch name.

Below this information, there are fields to enter the SSH URI and private key, where we will enter the SSH credentials Metaplane will use to read data from the repository. We'll walk through generating and storing these credentials in the next few steps of this doc.

Supported Git hosts

Currently, Git repository URLs from the following Git hosts are supported out of the box:

• github.com
• bitbucket.org

If your repository URL uses a different Git provider (for example, GitHub enterprise), please reach out to your Metaplane representative and ask about adding your Git host as a trusted Git provider. We can support nearly any Git host that supports SSH, we just need to manually verify the host first and add it as a trusted provider, which can be done very quickly.

Unsupported Git hosts

Looker bare repositories are the only Git host we cannot support. A bare repository's remote URL is a folder within the Looker server itself, which Metaplane is not able to access from the outside.

Identifying bare repositories

You'll be able to recognize a bare repository in the Metaplane UI because its repository URL will be a relative file path instead of a full URL. For example:

What to do if you have a bare repository

If this is a project that you created manually, we recommend migrating this repository to a supported Git provider like github.com - Looker makes this process relatively painless! See their documentation here for more information.

Looker Marketplace applications are usually installed as barebones repositories as well. It's generally not as important or useful to connect Metaplane to Marketplace project repositories - you can ignore these.

Generating SSH credentials for a repository

Your Git provider will have its own instructions for creating and registering SSH keys, and for getting the remote SSH url used to clone your repository.

Since it's so widely used, we provide some tips for setting up a connection to a github.com repo here.

github.com

If you're using github.com, you've got the choice of generating deploy keys or personal SSH keys. A deploy key is essentially an SSH key that only provides access to a single repository, while the standard personal SSH key generally provides access to all repositories that you, as a user, have access to. If you have many LookML repositories, you may find it easier to generate one SSH key that has access to all of them and give Metaplane the same private key for each repo.

See the GitHub docs for creating and adding a new SSH key, or for creating and adding a deploy key for a repository, depending on which option you want to do. You can also use the GitHub CLI for creating and registering both types of SSH keys, which is often the easiest way to do it, especially for deploy keys. You can find documentation on that here.

After generating your SSH key pair, you'll find the private key contents in a file, usually located in ~/.ssh/<keyname>. There will be a corresponding public key in ~/.ssh/<keyname>.pub, which you do not need to provide to Metaplane.

Identifying the Git remote SSH URI

Navigate to your repository in the browser, click the green <> Code dropdown and select SSH to view the SSH URI used to clone the repository over SSH.

Entering the SSH credentials in Metaplane

Once you've got the SSH URI used to clone the repository, and an SSH private key that has been added to your Git provider (and, optionally, the passphrase associated with the key, if you opted to use one), you're ready to add these credentials in Metaplane.

Navigate to your Looker connection in Metaplane, and click the Edit Git configuration button in the top-right corner.

Find the project you want to enter Git credentials for, enter the SSH URI, SSH private key, and optional key passphrase, hit Save, and you're good to go! The next time your Looker source syncs, it will use the contents of the connected LookML repository to build a complete view of the column-level lineage from your data warehouses to your Looker Explores, Dashboards, and more. You can also hit the Sync button to trigger a sync right away.

Troubleshooting

Sync error: UnknownHostKey

This indicates you're attempting to use a Git provider which Metaplane does not yet support. Don't worry, adding a new Git provider is quick and easy! Just reach out to your Metaplane representative for help.

Sync error: invalid privatekey

This indicates the SSH private key you provided is malformed in some way. Make sure you provide the entire contents of the private key file, include the lines starting with -----BEGIN... and ----END.... On MacOS, you can easily copy these contents to the clipboard by running cat <privatekeyfile> | pbcopy.

Sync error: Auth fail for methods 'publickey'

This indicates that the SSH private key you provided was rejected by the host. Make sure that you have registered the corresponding public key with your Git provider. For instructions on doing this with GitHub, see their docs.