此页面由 Cloud Translation API 翻译。

Looker CI/CD 安装和配置

本页介绍了如何安装和配置必要的组件，以实现 Looker 中的 CI/CD 工作流。

以下说明使用了包含开发、质量检查和生产环境的三层系统。不过，同样的原则也可以应用于两层或四层系统。

这些说明还假定您使用 GitHub 作为 Git 提供程序。您可以使用其他 Git 提供商来创建 CI/CD 工作流；不过，您必须具备相应的专业知识，才能根据您的提供商修改这些说明。

请按照与您相关的部分中的说明操作：

前提条件
仅限首次设置的步骤
适用于每位 Looker 开发者的设置步骤

前提条件

Linux 环境

此过程使用名为 Gazer 和 Spectacles 的工具，这些工具专为与类 Unix 操作系统搭配使用而设计。每个 LookML 开发者都必须有权访问您计划在其中运行 CI/CD 工作流的 Linux 环境或 macOS 中的命令行。

如果您使用的是 Windows，则可以在 Microsoft 的适用于 Linux 的 Windows 子系统 (WSL) 中使用 Gazer 和 Spectacles。借助 WSL，您可以运行各种不同的 Linux 发行版。如果您没有首选的 Linux 操作系统，最新版本的 Ubuntu Linux 是一个不错的选择，因为它具有广泛的支持。

这些说明提供了适用于 Linux 系统的示例，如果您使用的是 macOS 或 WSL，则可能需要进行修改。

每个层级一个 Looker 实例

如需启用此配置，您需要为系统的每个层级配置一个 Looker 实例。例如，如果系统包含开发阶段、质量检查阶段和生产阶段，则需要三个单独的实例。这些实例可以由 Google 托管，也可以由客户托管。

相同的连接名称

数据库连接在每个 Looker 实例中应具有相同的名称，无论它们代表的层级如何。例如，sales 连接在所有实例中都应使用该名称，而不是 sales_dev 或 sales_qa。

这些连接可以指向同一数据库，也可以指向不同的数据库。但是，如果它们指向同一数据库，则应定义不同的预留架构，以便开发或质量检查实例中的永久派生表不会干扰生产环境。

例如，如果所有三个实例都使用同一数据库，则它们的配置可能如下所示：

	生产	质量检查	开发
连接名称	`sales`	`sales`	`sales`
数据库	`sales_db`	`sales_db`	`sales_db`
Scratch 架构	`prod_sales_scratch`	`qa_sales_scratch`	`dev_sales_scratch`

或者，如果为所有三个实例使用唯一的数据库，则可以将它们配置如下：

	生产	质量检查	开发
连接名称	`sales`	`sales`	`sales`
数据库	`sales_db_prod`	`sales_db_qa`	`sales_db_dev`
Scratch 架构	`sales_scratch`	`sales_scratch`	`sales_scratch`

Git 代码库

所有三个层级中的每个项目都将使用一个 git 代码库。开发实例将跟踪 main 分支，而质量检查实例和生产实例通常会指向 git 标记（稍后会详细介绍）。

仅限首次设置的步骤

拥有 Looker 管理员权限以及其 Git 提供程序的管理员权限的用户只需完成本部分中的步骤一次。

Git 凭据

每个开发者的 Linux 环境都需要连接到您用于管理 LookML 的同一代码库。这可能是一个托管在 GitHub 等服务中的外部代码库。您需要拥有该服务的账号，并且该账号必须具有适当的凭据来配置代码库。您可以使用该账号设置 SSH 密钥，以允许您的 Linux 环境自动连接到该服务。

对于 GitHub，请按照向 GitHub 账号添加新的 SSH 密钥中的说明操作。

创建和配置 Git 服务器代码库

为了使 CI/CD 工作流正常运行，LookML 必须存储在 Git 代码库中，并与 Looker 项目相关联。在项目设置中，必须将 Git 生产分支名称设置为 main，并启用启用高级部署模式。

如果您尚未执行以下步骤，请按照 GitHub 的以下说明操作：

创建新代码库

在 GitHub 界面中，按右上角的 + 按钮，然后选择新建代码库。
选择所有者（可能是贵组织），然后输入 REPOSITORY_NAME。
选择将代码库设为公开还是私有（私有代码库需要付费订阅 GitHub），然后选中相应复选框以使用 README 文件初始化代码库。
按创建代码库按钮。
按标签为 <> Code 的绿色按钮，然后复制 SSH 网址。它看起来类似于：git@github.com:org_name/REPOSITORY_NAME.git。
在 Looker 中，创建新项目。
进入开发模式，然后从左侧边栏中选择“项目设置”项，再选择配置 Git。
粘贴代码库网址（在此示例中为 git@github.com:org_name/REPOSITORY_NAME.git），然后选择继续。
复制部署密钥，然后返回此代码库的 GitHub 界面。
依次选择设置和部署密钥。
点击添加部署密钥按钮，然后将部署密钥粘贴到密钥字段中。
添加标题（例如 Looker-REPOSITORY_NAME），选中允许写入权限复选框，然后按添加密钥按钮。
返回 Looker，然后选择测试并最终确定设置。
再次从左侧边栏中选择“项目设置”。将 Git 正式版分支名称更改为 main。
选择启用高级部署模式，然后选择保存项目配置。

在左侧的项目设置图标下方，您应该会看到 Deployment Manager 的部署图标。

使用现有代码库

前往存储 LookML 的 GitHub 代码库。
按标签为 <> Code 的绿色按钮，然后复制 SSH 网址。它看起来类似于：git@github.com:org_name/REPOSITORY_NAME.git。
在 Looker 中，创建新项目。
进入开发模式，然后从左侧边栏中选择“项目设置”项，再选择配置 Git。
粘贴代码库网址（在此示例中为 git@github.com:org_name/REPOSITORY_NAME.git），然后选择继续。
复制部署密钥，然后返回此代码库的 GitHub 界面。
依次选择设置和部署密钥。
点击添加部署密钥按钮，然后将部署密钥粘贴到密钥字段中。
添加标题（例如 Looker-REPOSITORY_NAME），选中允许写入权限复选框，然后按添加密钥按钮。
返回 Looker，然后选择测试并最终确定设置。
再次从左侧边栏中选择“项目设置”。将 Git 正式版分支名称更改为 main。
选择启用高级部署模式，然后选择保存项目配置。

在左侧的项目设置图标下方，您应该会看到 Deployment Manager 的部署图标。

创建 GitHub Actions

创建多个 GitHub 操作非常有用，这样每次进行 LookML 更改时，系统就会自动执行各种检查。若要添加这些操作，您需要能够在 Linux 环境中更改 Git 代码库。如果尚未安装，请按照配置 Git 中的说明操作。

如需添加 GitHub 操作，请前往 Linux 环境中代码库的目录，然后添加子目录 .github/workflows。设置完成后，您可以从 GitHub 界面的操作页面手动运行这些操作。

Look-At-Me-Sideways (LAMS)

LAMS 是一个开源 lint 工具，用于检查 LookML 是否存在错误和不良做法。将一个名为 lams.yml 的文件添加到 .github/workflows 目录中，其中包含以下内容：

name: LAMS

on:
  pull_request:
    branches: [ main ]
  push:
  workflow_dispatch:

jobs:
  lams_job:
    runs-on: ubuntu-latest
    name: LAMS LookML Linter Job
    steps:
    - name: Checkout your LookML
      uses: actions/checkout@v1
    - name: Setup Node
      uses: actions/setup-node@v1
      with:
        node-version: '16.x'
    - name: Install LAMS
      run: npm install -g @looker/look-at-me-sideways@3
    - name: Run LAMS
      run: lams --reporting=no

每次将提交推送到 GitHub 或打开拉取请求以将代码与 main 分支合并时，LAMS 都会运行。

Release Please

Release Please 是一款开源工具，可自动为版本添加正确的版本号标记。

将一个名为 release-please.yml 的文件添加到 .github/workflows 目录中，其中包含以下内容：

name: release-please

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v3
        with:
          release-type: simple
          package-name: sales_project

传统提交

此 GitHub Action 可确保拉取请求的标题符合传统提交标准。

将一个名为 lint_pr_title.yml 的文件添加到 .github/workflows 目录中，其中包含以下内容：

name: "Lint Pull Request Title"

on:
  pull_request_target:
    types:
      - opened
      - edited
      - synchronize

jobs:
  main:
    name: Validate PR title
      runs-on: ubuntu-latest
      steps:
        - uses: amannn/action-semantic-pull-request@v5
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

将更改推送到 GitHub

最后，使用以下命令提交这些 GitHub 操作更改并将其推送到 GitHub：

git add .github/workflows/
git commit -m "chore: Added github actions"
git push

保护 `main` 分支

在 GitHub 界面中，您应为 main 分支启用分支保护，以便普通开发者无法直接将更改推送到该分支。而是在其他分支中进行更改，然后打开拉取请求。拉取请求在获得批准并与 main 合并之前，可以由其他开发者进行审核。

如需配置分支保护，请前往相应代码库的 GitHub 界面，依次选择 Settings（设置）和 Branches（分支），然后按 Add branch protection rule（添加分支保护规则）按钮：

用于添加分支保护的 GitHub 界面。

输入 main 作为分支名称模式，然后选中以下选项：

合并前要求提交拉取请求
需要审批
在有新的提交内容推送时忽略过时的拉取请求批准

用于设置分支保护选项的 GitHub 界面。

最后，按页面底部的创建按钮。

创建拉取请求后，系统会运行在本说明中前面配置的 GitHub Actions。首次运行后，您还可以在此界面中选择这些测试，以便在拉取请求合并到 main 之前，这些测试必须成功运行。

配置拉取请求

在 Looker 中，您可以要求使用拉取请求，并让 Looker 代表开发者打开 PR。此参数应仅针对开发实例进行配置。质量检查实例和生产实例将使用高级部署模式来获取更新。

如需启用此功能，请前往每个项目的项目配置页面，然后在 GitHub 集成标题下选择需要拉取请求。

按相应按钮设置网络钩子 Secret，复制生成的随机字符串，然后按 Save Project Configuration（保存项目配置）按钮。

返回代码库的 GitHub 界面，依次选择 Settings（设置）和 Webhooks（Webhook）。按右上角的添加 Webhook 按钮：

在标记为载荷网址的字段中，输入 https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy
在标记为 Secret 的字段中，粘贴您从 Looker 中保存的 Secret
对于问题“您想通过哪些事件触发此 Webhook？”，请选择让我选择个别事件

用于配置 webhook 的 GitHub 界面。

确保选择了拉取请求和推送：

用于拉取请求和推送的 GitHub 复选框。

最后，按页面底部的 Add webhook（添加 Webhook）按钮。

适用于每位 Looker 开发者的设置步骤

以下所有安装步骤都应在 Linux 环境中执行。

安装 Ruby

您需要安装 Ruby 编程语言才能运行 Gazer。2.7.7 之后的任何版本的 Ruby 都适用于 Gazer，但首选 Ruby 3.x.x。如需在 Ubuntu Linux 上安装 Ruby，请运行以下命令：

sudo apt update
sudo apt install ruby

运行 ruby -v 以确认 Ruby 已正确安装。您应该会看到如下所示的响应：

ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]

这些命令也适用于 Debian Linux、Linux Mint 以及使用 Aptitude 软件包管理器的其他几种 Linux 发行版。您可能需要搜索适用于其他 Linux 版本的命令，或搜索适用于在 macOS 上安装的命令。如需了解详情，请参阅安装 Ruby。

安装 Gazer

Gazer 是由 Google 员工创建的一个开源项目，可让您使用命令行工具浏览和管理聊天室、外观和信息中心。

安装 Ruby 后，您可以使用 Ruby 的 Gem 工具安装 Gazer：

gem install gazer

使用 gzr version 命令确认是否已安装 Gazer。您应该会看到如下所示的响应：

v0.3.12

安装 Spectacles

Spectacles 是一款用于测试 LookML 的非 Google 工具。Spectacles 提供付费版本和开源版本，您可以在其使用入门页面上找到安装详情。

安装 Git

您可以使用以下命令在 Ubuntu Linux 上安装 Git 版本控制软件：

sudo apt update
sudo apt install git

使用 git --version 命令确认安装是否成功。您应该会看到类似以下内容的响应：

git version 2.42.0.609.gbb76f46606

这些命令也适用于 Debian Linux、Linux Mint 以及使用 Aptitude 软件包管理器的其他几种 Linux 发行版。您可能需要搜索适用于其他 Linux 发行版本的命令。例如，如需了解适用于 Fedora 和 macOS 的说明，请参阅开始使用 - 安装 Git。

配置 Git

您需要配置 Linux 环境中的 Git，以便与存储 LookML 的任意 Git 代码库进行交互。这些说明适用于存储在 GitHub 中的 LookML Git 代码库。

姓名和电子邮件地址

GitHub（以及大多数其他 Git 实现）需要知道您的姓名和电子邮件地址，以便记录活动。运行以下命令，在 Git 中配置您的姓名和电子邮件地址：

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "EMAIL_ADDRESS"

Git 凭据

在初始 CI/CD 设置中，创建了 Git 凭据。生成的 SSH 私钥应在 $HOME/.ssh/config 文件中进行配置。如需创建该文件，请使用以下命令：

touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config

将以下文本插入 $HOME/.ssh/config 文件中：

Host github.com
  User git
  IdentityFile ~/.ssh/KEY_NAME
  ControlMaster auto
  ControlPath ~/.ssh/ctrl-%r@%h:%p
  ControlPersist yes

使用您按照向 GitHub 账号添加新的 SSH 密钥说明生成的私钥文件的名称，替换 KEY_NAME。私钥文件与公钥文件同名，但不带 .pub 扩展名。例如，如果您使用的是文件 id_ed25519.pub 中找到的公钥，则私钥将命名为 id_ed25519。

设置本地 Git 代码库

配置 LookML 代码库后，您需要在 Linux 环境中创建一个副本。为此，请运行以下命令：

git clone GIT_URL

例如，该命令可能如下所示：

git clone git@github.com:my_org_name/sales_project.git

这会将 LookML 代码库复制到子目录（例如 sales_project）。使用 cd SUB_DIRECTORY 命令进入代码库。在此示例中，该命令将为 cd sales_project。

进入代码库目录后，您可以使用以下命令：

命令	用途
`git checkout BRANCH_NAME`	用于切换分支。在大多数情况下，主分支称为 `main`；不过，在较旧的系统中，它可能称为 `master`。
`git fetch`	用于从服务器检索最新更改。
`git pull`	用于将更改应用于已检出的本地文件。`git pull` 会隐式执行 `git fetch`。
`git tag`	用于为特定修订版本创建有意义的标记。
`git push`	用于将本地更改推送到服务器。

配置 Gazer

若要使用 Gazer，您需要拥有每个开发、质量检查和生产实例的 API 凭据。如需了解如何创建 API 凭据，请参阅管理设置 - 用户页面。API 凭据可能已由最初设置 CI/CD 工作流的人员创建。在这种情况下，您可以使用现有凭据；无需为每个用户生成新的凭据。

将您的 API 凭据存储在主目录中具有最低权限的 .netrc 文件中。您可以使用以下命令创建具有正确权限的空文件：

touch $HOME/.netrc
chmod 600 $HOME/.netrc

将以下条目添加到该文件中，但请使用您自己的 Looker 服务器主机名作为 machine，使用 API client_id 作为登录信息，并使用 API client_secret 作为密码。例如：

machine dev.example.looker.com
  login 80ka7nl6lj87ftmn
  password u7kw3mj5h2trfz0

machine qa.example.looker.com
  login fi3qtv5at5crvd1q
  password bdxtaeghnzyz0wm

machine example.looker.com
  login k7lr6yv57wvzy9p2
  password wcvr5qjd2isbs2s

对每个服务器运行简单的 Gazer 命令（例如以下命令），以测试其是否正常运行：

gzr user me --host dev.example.looker.com

您应该会看到类似如下所示的结果：

+----+---------------+---------+----------+------------------+--------------+
|  id|email          |last_name|first_name|personal_folder_id|home_folder_id|
+----+---------------+---------+----------+------------------+--------------+
|2345|jsm@example.com|Smith    |John      |              2161|           708|
+----+---------------+---------+----------+------------------+--------------+

如果上一个命令不起作用，您可能需要在 gzr 命令的末尾添加 --port 443，如下所示：

gzr user me --host dev.example.looker.com --port 443

配置 Spectacles

Spectacles 使用与 Gazer 相同的 API client_id 和 client_secret。在 Spectacles 目录中，为每个层级创建一个名为 config-TIER.yaml 的文件，例如 config-dev.yaml。根据相应层级的 Looker 实例，将以下内容添加到文件中，例如：

config-dev.yaml

base_url: https://dev.example.looker.com/
client_id: 80ka7nl6lj87ftmn
client_secret: u7kw3mj5h2trfz0

config-qa.yaml

base_url: https://qa.example.looker.com/
client_id: fi3qtv5at5crvd1q
client_secret: bdxtaeghnzyz0wm

config-prod.yaml

base_url: https://example.looker.com/
client_id: k7lr6yv57wvzy9p2
client_secret: wcvr5qjd2isbs2s

您可以通过运行以下命令并替换每个文件名来测试每个文件：

$ spectacles connect --config-file config-dev.yaml

您应该会看到如下所示的响应：

Connected to Looker version 23.18.60 using Looker API 4.0

Looker CI/CD 安装和配置

前提条件

Linux 环境

每个层级一个 Looker 实例

相同的连接名称

Git 代码库

仅限首次设置的步骤

Git 凭据

创建和配置 Git 服务器代码库

创建新代码库

使用现有代码库

创建 GitHub Actions

Look-At-Me-Sideways (LAMS)

Release Please

传统提交

将更改推送到 GitHub

保护 main 分支

配置拉取请求

适用于每位 Looker 开发者的设置步骤

安装 Ruby

安装 Gazer

安装 Spectacles

安装 Git

配置 Git

姓名和电子邮件地址

Git 凭据

设置本地 Git 代码库

配置 Gazer

配置 Spectacles

保护 `main` 分支