将 CI/CD 集成到 Snowflake CLI 中¶

Snowflake CLI 可与流行的 CI/CD（持续集成和持续交付）系统和框架集成，如 GitHub Actions (https://github.com/features/actions)，从而高效地使 Snowflake 中的 SQL、Snowpark、原生应用程序或 Notebook 工作流程自动化。

下图展示了一个典型的 Snowflake CLI 中的 CI/CD 工作流程。

CI/CD 工作流程步骤¶

存储： 配置远程 Git 存储库以安全地管理 Snowflake 文件。
代码： 使用 IDE 或 Snowsight 开发 Snowflake 代码，可根据个人偏好进行定制。
安装： 安装 Snowflake CLI，并配置您偏好的 CI/CD 提供商，如 GitHub Actions。
部署： 将 Snowflake CLI 与您选择的 CI/CD 工具结合使用，实现自动化部署。
监控： 借助 Snowflake Trail，跟踪 Snowflake 中的代码和工作流程性能，以获得实时见解。
迭代： 对项目进行少量、频繁的更新以实现持续改进；如有必要，较小的更改可简化管理和回滚。

使用 GitHub Actions 实现 CI/CD¶

A Snowflake CLI action is a GitHub action designed to integrate Snowflake CLI into CI/CD pipelines. You can use it to automate execution of Snowflake CLI commands within your GitHub workflows. For more information, see the snowflake-cli-action (https://github.com/snowflakedb/snowflake-cli-action) repository.

使用 Snowflake CLI Actions¶

Github Actions streamlines the process of installing and using Snowflake CLI in your CI/CD workflows. The CLI is installed in an isolated way, ensuring that it won't conflict with the dependencies of your project. It automatically sets up the input configuration file within the ~/.snowflake/ directory.

该操作可自动完成您的 Snowflake CLI 任务，例如在 Snowflake 环境中部署 Snowflake Native Apps 或运行 Snowpark 脚本。

输入参数¶

Snowflake CLI Action 在 Github 工作流程 YAML 文件中使用以下输入参数，例如 <repo-name>/.github/workflows/my-workflow.yaml：

cli-version: The specified Snowflake CLI version, such as 3.11.0. If not provided, the latest version of the Snowflake CLI is used.
custom-github-ref：要直接从中安装 Snowflake CLI 的 Github 存储库中的分支、标签或提交。

备注

您不能同时使用 cli-version 和:codenowrap:custom-github-ref；只能指定其中一个参数。
default-config-file-path: Path to the configuration file (config.toml) in your repository. The path must be relative to the root of the repository. The configuration file is not required when a temporary connection (-x option) is used. For more information, see 管理 Snowflake 连接.
use-oidc：启用 OIDC 身份验证的布尔标志。当设置为 true 时，该操作会配置 CLI 以将 GitHub 的 OIDC 令牌用于向 Snowflake 进行身份验证，从而无需将私钥存储为密钥。默认值为 false。

从 GitHub 分支或标签安装 Snowflake CLI¶

要在 GitHub 存储库中的特定分支、标签或提交中安装 Snowflake CLI（例如，测试未发布的功能或分支），请使用以下配置：

- uses: snowflakedb/snowflake-cli-action@v2.0
  with:
    custom-github-ref: "feature/my-branch" # or a tag/commit hash

Copy

您还可以包括其他输入参数。

此功能在 snowflake-cli-action 版本 1.6 或更高版本中可用。

在 CI/CD 工作流程中安全地配置该 Action¶

You can safely configure the action in your CI/CD workflow by using either of the following methods:

使用工作负载身份联合 (WIF) OpenID Connect (OIDC) 身份验证
使用私钥身份验证

使用工作负载身份联合 (WIF) OpenID Connect (OIDC) 身份验证¶

备注

WIF OIDC 身份验证需要 Snowflake CLI 版本 3.11.0 或更高版本。

WIF OIDC 身份验证为使用 Snowflake 进行身份验证提供了一种安全的现代化方式，无需将私钥存储为密钥。这种方法使用 GitHub 的 OIDC (OpenID Connect) 令牌向 Snowflake 进行身份验证。

To set up WIF OIDC authentication, follow these steps:

通过使用 OIDC 工作负载身份类型设置服务用户来配置 WIF OIDC：

CREATE USER <username>
TYPE = SERVICE
WORKLOAD_IDENTITY = (
  TYPE = OIDC
  ISSUER = 'https://token.actions.githubusercontent.com'
  SUBJECT = '<your_subject>'
)

Copy

备注

默认情况下，您的主题应如下所示：repo:<repository-owner/repository-name>:environment:<environment>。

要简化主题生成过程，请使用 gh 命令，其中 <environment_name> 是在存储库设置中定义的环境，如以下示例所示：

gh repo view <repository-owner/repository-name> --json nameWithOwner | jq -r '"repo:\(.nameWithOwner):environment:<environment_name>"'
Copy
有关自定义主题的更多信息，请参阅 GitHub 上的 OpenID Connect (https://docs.github.com/en/actions/reference/security/oidc) 参考文档。

Store your Snowflake account identifier in GitHub secrets. For more information, see GitHub Actions documentation (https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).

Configure the Snowflake CLI action in your GitHub workflow YAML file, as shown:

name: Snowflake OIDC
on: [push]

permissions:
  id-token: write  # Required for OIDC token generation
  contents: read

jobs:
  oidc-job:
    runs-on: ubuntu-latest
    environment: test-env # this should match the environment used in the subject
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Set up Snowflake CLI
        uses: snowflakedb/snowflake-cli-action@v2.0
        with:
          use-oidc: true
          cli-version: "3.11"
      - name: test connection
        env:
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
        run: snow connection test -x

Copy

有关为您的 Snowflake 账户设置 WIF OIDC 身份验证和配置 GitHub OIDC 提供程序的更多信息，请参阅工作负载身份联合。

使用私钥身份验证¶

要使用私钥身份验证，您需要将 Snowflake 私钥存储在 GitHub 密钥中，并配置 Snowflake CLI 操作以使用它。

将您的 Snowflake 私钥存储在 GitHub 密钥中。

For more information, see GitHub Actions documentation (https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).

Configure the Snowflake CLI action in your GitHub workflow YAML file, as shown:

name: Snowflake Private Key
on: [push]

jobs:
  private-key-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Set up Snowflake CLI
        uses: snowflakedb/snowflake-cli-action@v2.0

Copy

定义连接¶

您可以定义一个 GitHub Action，以通过临时连接或配置文件中定义的连接来连接 Snowflake。有关管理连接的更多信息，请参阅管理 Snowflake 连接。

使用临时连接¶

有关临时连接的更多信息，请参阅使用临时连接。

要为临时连接设置 Snowflake 凭据，请按照以下步骤操作：

在 GitHub 工作流程中，将密钥映射为环境变量，格式为 SNOWFLAKE_<key>=<value>，示例如下：

env:
  SNOWFLAKE_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
  SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}

Copy

配置 Snowflake CLI Action。

If you use the latest version of Snowflake CLI, you do not need to include the cli-version parameter. The following example instructs the action to use Snowflake CLI version 3.11.0 specifically:
```
- uses: snowflakedb/snowflake-cli-action@v2.0
  with:
    cli-version: "3.11.0"
```
Copy
可选：Snowflake 使用此加密短语来解密私钥。例如：
```
- name: Execute Snowflake CLI command
  env:
    PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }}
```
Copy
要使用密码而不是私钥，请取消设置 SNOWFLAKE_AUTHENTICATOR 环境变量，然后添加 SNOWFLAKE_PASSWORD 变量，如下所示：
```
- name: Execute Snowflake CLI command
  env:
    SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
    SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
    SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
```
Copy
备注

为提升您在使用密码和 MFA 时的体验，Snowflake 建议您配置 MFA 缓存。

有关如何在环境变量中设置 Snowflake 凭据的详细信息，请参阅为 Snowflake 凭据使用环境变量；关于如何在 GitHub CI/CD 工作流程中定义环境变量的详细信息，请参阅为单个工作流程定义环境变量 (https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow)。

通过临时连接，添加要执行的 snow 命令，如下所示：

run: |
  snow --version
  snow connection test --temporary-connection

Copy

以下示例显示了已完成的示例 <repo-name>/.github/workflows/my-workflow.yaml 文件：

name: deploy
on: [push]

jobs:
  version:
    name: "Check Snowflake CLI version"
    runs-on: ubuntu-latest
    steps:
      # Snowflake CLI installation
      - uses: snowflakedb/snowflake-cli-action@v2.0

        # Use the CLI
      - name: Execute Snowflake CLI command
        env:
          SNOWFLAKE_AUTHENTICATOR: SNOWFLAKE_JWT
          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
          PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }} # Passphrase is only necessary if private key is encrypted.
        run: |
          snow --help
          snow connection test -x

Copy

在验证 Action 可以成功连接到 Snowflake 之后，您可以添加更多 Snowflake CLI 命令，如 snow notebook create 或 snow git execute。有关支持的命令的信息，请参阅 Snowflake CLI 命令参考。

使用配置文件¶

有关定义连接的更多信息，请参阅定义连接。

要为特定连接设置 Snowflake 凭据，请执行以下步骤：

Create a config.toml file at the root of your Git repository with an empty configuration connection, as shown:
```
default_connection_name = "myconnection"

[connections.myconnection]
```
Copy
此文件用作模板，不应包含实际凭据。

在 GitHub 工作流程中，将密钥映射为环境变量，格式为 SNOWFLAKE_<key>=<value>，示例如下：

env:
  SNOWFLAKE_CONNECTIONS_MYCONNECTION_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
  SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}

Copy

配置 Snowflake CLI Action。

如果您使用的是最新版本的 Snowflake CLI，则无需添加 cli-version 参数。以下示例指定了所需的版本和默认配置文件的名称：
```
- uses: snowflakedb/snowflake-cli-action@v2.0
  with:
    cli-version: "3.11.0"
    default-config-file-path: "config.toml"
```
Copy

可选：Snowflake 使用此加密短语来解密私钥。例如：

- name: Execute Snowflake CLI command
  env:
    PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }}

Copy

要使用密码而不是私钥，请取消设置 SNOWFLAKE_AUTHENTICATOR 环境变量，然后添加 SNOWFLAKE_PASSWORD 变量，如下所示：

- name: Execute Snowflake CLI command
  env:
    SNOWFLAKE_CONNECTIONS_MYCONNECTION_USER: ${{ secrets.SNOWFLAKE_USER }}
    SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
    SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}

Copy

备注

为提升您在使用密码和 MFA 时的体验，Snowflake 建议您配置 MFA 缓存。

使用命名连接添加要执行的 snow 命令，如下所示：
```
run: |
  snow --version
  snow connection test
```
Copy

以下示例显示了 Git 存储库中的示例 config.toml 文件和已完成的示例 <repo-name>/.github/workflows/my-workflow.yaml 文件：

示例 config.toml 文件：

default_connection_name = "myconnection"

[connections.myconnection]

Copy

示例 Git 工作流程文件：

name: deploy
on: [push]
jobs:
  version:
    name: "Check Snowflake CLI version"
    runs-on: ubuntu-latest
    steps:
      # Checkout step is necessary if you want to use a config file from your repo
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          persist-credentials: false

        # Snowflake CLI installation
      - uses: snowflakedb/snowflake-cli-action@v2.0
        with:
          default-config-file-path: "config.toml"

        # Use the CLI
      - name: Execute Snowflake CLI command
        env:
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_AUTHENTICATOR: SNOWFLAKE_JWT
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
          PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }} #Passphrase is only necessary if private key is encrypted.
        run: |
          snow --help
          snow connection test

Copy