O que é um heredoc em YAML? Explicado

Um heredoc em YAML é um here-document de shell escrito dentro de um bloco multilinha YAML, permitindo que uma etapa de CI forneça um trecho de texto a um comando.

Um heredoc é um recurso de shell para fornecer um bloco de texto a um comando, e as pessoas frequentemente querem um dentro de uma etapa run do YAML - para escrever um arquivo de configuração, canalizar um script para uma ferramenta ou passar um bloco SQL. Combinar um heredoc de shell com escalares de bloco YAML funciona bem, mas as regras de indentação e expansão de variáveis de ambas as camadas podem te enganar.

Heredoc mais bloco YAML

Um heredoc inicia um bloco de entrada que termina em uma palavra marcadora escolhida. Dentro de uma etapa run do YAML, você escreve o heredoc dentro de um escalar de bloco literal para que o shell veja as linhas literalmente. A camada YAML preserva as quebras de linha; a camada de shell as consome como entrada do heredoc.

Interação de indentação

Dois sistemas de indentação se acumulam aqui: o YAML exige que todo o bloco seja indentado sob run, enquanto o marcador de fechamento do heredoc de shell deve seguir suas próprias regras. Usar a forma com traço do operador de heredoc permite indentar o corpo com tabs para melhor legibilidade, mas os espaços não serão removidos - uma fonte frequente de erros de "marker not found".

As aspas no marcador controlam a expansão

Se as variáveis de shell dentro do heredoc são expandidas depende do marcador. Um marcador sem aspas expande variáveis e substituições de comando; um marcador com aspas passa o texto de forma literal. Escolher errado significa ou um literal não expandido ou um valor interpolado acidentalmente.

Heredocs em CI

Um padrão comum é escrever um arquivo de configuração a partir de uma etapa run usando um heredoc, muitas vezes combinado com a saída multilinha ou a sintaxe de arquivo de ambiente do GitHub Actions, que ela mesma usa um delimitador no estilo heredoc para passar com segurança valores de múltiplas linhas entre etapas.

# Heredoc inside a YAML run block to write a file
steps:
  - run: |
      cat > config.yml <<'EOF'
      server: prod
      retries: 3
      EOF

Nota Latchkey

Heredocs e a sintaxe de arquivo de ambiente multilinha rodam de forma idêntica nos runners da Latchkey, então padrões como escrever um arquivo de configuração ou passar a saída de um job com múltiplas linhas funcionam sem qualquer alteração.

Principais conclusões

• Um heredoc em YAML é um here-document de shell escrito dentro de um escalar de bloco literal em uma etapa run.
• A indentação do YAML e as regras do marcador de fechamento do heredoc se acumulam, então erros de indentação são comuns.
• Colocar aspas no marcador do heredoc decide se as variáveis de shell dentro dele são expandidas ou deixadas literais.

Guias relacionados