GitHub Action na Snowflake CLI¶

O GitHub Action na Snowflake CLI (snowflakedb/snowflake-cli-action) instala e configura a Snowflake CLI em um fluxo de trabalho do GitHub Actions. Use-o para automatizar as implantações do Snowflake (projetos DCM, aplicativos Snowpark, Snowflake Native Apps e scripts SQL) do seu repositório GitHub.

Como funciona¶

A ação executa estas etapas no executor:

Instala o Python 3.11 e o gerenciador de pacotes uv usando astral-sh/setup-uv.
Instala a Snowflake CLI em um ambiente isolado (uv tool install snowflake-cli).
Copia config.toml do repositório para ~/.snowflake/config.toml (0600 no Linux/macOS). Ignorada se o arquivo estiver ausente.
Quando a autenticação OIDC está habilitada, obtém um token OIDC emitido pelo GitHub e define as variáveis do ambiente de identidade da carga de trabalho do Snowflake para as etapas subsequentes.

Após a conclusão da ação, o comando snow fica disponível em PATH para cada etapa subsequente no trabalho.

Exemplo de uso rápido¶

O fluxo de trabalho a seguir faz a autenticação com o Snowflake usando OIDC e executa um teste de conexão:

name: Deploy to Snowflake
on:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - uses: snowflakedb/snowflake-cli-action@v2
        with:
          use-oidc: true
          cli-version: "3.16"

      - name: Deploy
        env:
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
        run: |
          snow connection test -x
          snow dcm deploy --target PROD -x

Para outros métodos de autenticação, consulte Métodos de autenticação.

Fixação de versão¶

A ação oferece suporte a três estilos de fixação:

Commit SHA (@a1b2c3d...): fixa a uma confirmação específica.
Patch version tag (@v2.0.2): fixa a uma versão específica.
Floating major tag (@v2): segue a versão mais recente na respectiva versão principal.

# Pinned commit SHA.
- uses: snowflakedb/snowflake-cli-action@a1b2c3d4e5f67890abcdef1234567890abcdef12

# Patch version tag.
- uses: snowflakedb/snowflake-cli-action@v2.0.2

# Floating major tag.
- uses: snowflakedb/snowflake-cli-action@v2

Entradas¶

A ação aceita as seguintes entradas, especificadas em with: no fluxo de trabalho YAML:


Entrada	Obrigatório	Padrão	Descrição
`cli-version`	Não	(mais recente)	Versão da Snowflake CLI a ser instalada, por exemplo `3.16.0` ou `3.16`. Quando omitida, a última versão lançada é instalada.
`custom-github-ref`	Não	(nenhum)	Ramificação GitHub, tag ou confirmação da qual instalar a Snowflake CLI. Use esta entrada para testar recursos não lançados ou uma bifurcação. Mutualmente exclusiva com `cli-version`.
`default-config-file-path`	Não	`./config.toml`	Caminho para o `config.toml`, relativo à raiz do repositório. Consulte Gerenciando conexões Snowflake.
`use-oidc`	Não	`false`	Quando `true`, configura a autenticação OIDC obtendo um token OIDC do GitHub e definindo as variáveis do ambiente de identidade da carga de trabalho do Snowflake.
`oidc-token-name`	Não	`SNOWFLAKE_TOKEN`	Nome da variável de ambiente que o token OIDC usa para ser exportado. Defina-o como `SNOWFLAKE_CONNECTIONS_<NAME>_TOKEN` quando você usa uma conexão nomeada, em que `<NAME>` é o nome em maiúsculas da conexão do seu `config.toml` (por exemplo, para `[connections.myconnection]`, defina `SNOWFLAKE_CONNECTIONS_MYCONNECTION_TOKEN`). O nome da variável fica em maiúsculas internamente antes de ser exportado.

Nota

Especifique apenas uma das entradas cli-version ou custom-github-ref. Usar as duas ao mesmo tempo resulta em erro.

Métodos de autenticação¶

A ação oferece suporte a três métodos de autenticação com o Snowflake. A Snowflake recomenda o OIDC porque evita o armazenamento de segredos de longa duração no GitHub.


Método	Segurança	Segredos necessários	Versão do Snowflake CLI
Federação de identidade da carga de trabalho (WIF) com OIDC (recomendado)	Tokens sem segredo e de curta duração	Somente conta Snowflake	3.11 ou posterior
Autenticação por par de chaves	Chave privada armazenada em segredos do GitHub	Chave privada, conta, usuário	Qualquer
Autenticação de senha	Senha armazenada em segredos do GitHub	Senha, conta, usuário	Qualquer

Federação de identidade da carga de trabalho (WIF) com OIDC¶

Nota

A autenticação OIDC requer a Snowflake CLI versão 3.11.0 ou mais recente.

Com o OIDC, o GitHub emite um token OpenID Connect de curta duração que o Snowflake valida diretamente. Nenhuma chave privada ou senha é armazenada no GitHub.

Criar o usuário de serviço¶

Crie um usuário de serviço do Snowflake que confie no provedor OIDC do GitHub:

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

SUBJECT deve corresponder à declaração que o GitHub emite para o fluxo de trabalho. Use um dos seguintes formatos:


Formato da entidade	Corresponde a	Requisito de fluxo de trabalho
`repo:<owner>/<repo>:ref:refs/heads/<branch>`	Envio para a ramificação especificada	`on: push`, without `environment:` on the job
`repo:<owner>/<repo>:pull_request`	Qualquer evento de solicitação de pull	`on: pull_request`, sem `environment:` no trabalho
`repo:<owner>/<repo>:environment:<name>`	O destino do trabalho é um ambiente GitHub nomeado	O trabalho define `environment: <name>` (o ambiente deve existir nas configurações do repositório)

Quando um trabalho define environment:, o GitHub usa o formato do ambiente, seja qual for o acionador.

Para personalizar a entidade para incluir uma declaração mais ampla, como repository_owner, consulte a Referência do OpenID Connect do GitHub.

Configurar a ação¶

Conceda a permissão id-token: write ao trabalho e defina use-oidc: true na ação:

name: Snowflake OIDC
on:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  oidc-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: snowflakedb/snowflake-cli-action@v2
        with:
          use-oidc: true
          cli-version: "3.16"
      - name: Test connection
        env:
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
        run: snow connection test -x

Quando use-oidc: true é definido, a ação exporta as seguintes variáveis de ambiente para as etapas subsequentes:

SNOWFLAKE_AUTHENTICATOR=WORKLOAD_IDENTITY
SNOWFLAKE_WORKLOAD_IDENTITY_PROVIDER=OIDC
SNOWFLAKE_AUDIENCE=snowflakecomputing.com
SNOWFLAKE_TOKEN=<token> (ou a variável nomeada por oidc-token-name)

Para ver um contexto mais amplo, consulte Federação de identidades de carga de trabalho.

Autenticação por par de chaves¶

Armazene sua chave privada do Snowflake como um segredo do GitHub e passe-o através do ambiente. Você pode usar uma conexão temporária (sem necessidade do config.toml) ou uma conexão nomeada definida no config.toml.

Conexão temporária:

- uses: snowflakedb/snowflake-cli-action@v2
  with:
    cli-version: "3.16.0"
- name: Deploy
  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.PRIVATE_KEY_PASSPHRASE }}
  run: |
    snow connection test -x
    snow dcm deploy --target PROD -x

Conexão nomeada: confirme um config.toml com um bloco de conexão vazio e substitua os campos por meio de variáveis de ambiente:

default_connection_name = "myconnection"

[connections.myconnection]

- uses: snowflakedb/snowflake-cli-action@v2
  with:
    default-config-file-path: "config.toml"
- name: Deploy
  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.PRIVATE_KEY_PASSPHRASE }}
  run: snow connection test

Para obter mais informações sobre conexões, consulte Gerenciando conexões Snowflake.

Autenticação de senha¶

A autenticação de senha é compatível com fluxos de trabalho legados, mas não é recomendada para CI/CD de produção. Para usá-la, omita SNOWFLAKE_AUTHENTICATOR (a CLI usa como padrão a autenticação de senha) e passe SNOWFLAKE_PASSWORD:

- uses: snowflakedb/snowflake-cli-action@v2
- name: Deploy
  env:
    SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
    SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
    SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
  run: snow connection test -x

Nota

Ao usar uma senha e MFA, a Snowflake recomenda habilitar o armazenamento em cache de MFA.

Instalando de uma ramificação, tag ou conformação¶

Para testar uma mudança ou uma bifurcação da Snowflake CLI não lançada, use custom-github-ref:

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

Suporte à plataforma¶

A ação é executada em executores hospedados por GitHub no Ubuntu, macOS e Windows e é testada em Python 3.10 e 3.13. Observe o seguinte comportamento específico da plataforma:

Linux e macOS: o config.toml copiado é definido com permissões 0600.
Windows: permissões de arquivo em config.toml não são modificadas. Use segredos do GitHub para credenciais. Evite confirmar segredos para config.toml, seja qual for o executor.

GitHub Action na Snowflake CLI¶

Como funciona¶

Exemplo de uso rápido¶

Fixação de versão¶

Entradas¶

Métodos de autenticação¶

Federação de identidade da carga de trabalho (WIF) com OIDC¶

Criar o usuário de serviço¶

Configurar a ação¶

Autenticação por par de chaves¶

Autenticação de senha¶

Instalando de uma ramificação, tag ou conformação¶

Suporte à plataforma¶

Recursos relacionados¶