Boas Práticas de Linting YAML: Detecte Erros Antes do Deploy

Um espaço mal posicionado em um arquivo YAML pode derrubar um deploy em produção. Diferente do JSON, que falha de forma explícita em erros de sintaxe, o YAML pode silenciosamente interpretar uma indentação incorreta como estruturas de dados inesperadas. O linting detecta esses problemas antes que cheguem à produção.

Por Que Fazer Linting de YAML?

A flexibilidade do YAML é tanto sua força quanto sua fraqueza:

# Isto é YAML válido, mas provavelmente está errado
ports:
  - 80
  - 443
  name: webserver  # Esta é uma chave no SEGUNDO item da lista, não no mapeamento!

O exemplo acima cria uma lista onde o segundo item é um mapeamento {443: null, name: webserver}. Um linter detectaria esse problema de indentação. Sem linting, esse tipo de bug pode levar horas para diagnosticar.

yamllint: O Linter Padrão

O yamllint é o linter YAML mais amplamente utilizado. Ele verifica tanto a validade da sintaxe quanto a consistência de estilo.

Instalação

pip install yamllint

Uso Básico

# Lint em um único arquivo
yamllint config.yaml

# Lint em um diretório
yamllint .

# Lint com uma configuração específica
yamllint -c .yamllint.yml .

Configuração

Crie o arquivo .yamllint.yml na raiz do seu projeto:

extends: default

rules:
  line-length:
    max: 120
    level: warning
  indentation:
    spaces: 2
    indent-sequences: true
  truthy:
    allowed-values: ['true', 'false', 'yes', 'no']
  comments:
    require-starting-space: true
    min-spaces-from-content: 2
  document-start: disable
  empty-lines:
    max: 1

Regras Principais Explicadas

Regra	Finalidade	Configuração Recomendada
`indentation`	Impor indentação consistente	2 espaços, sem tabs
`line-length`	Evitar linhas muito longas	120 caracteres (aviso)
`truthy`	Controlar valores booleanos	Apenas `true`/`false`
`comments`	Formatação de comentários	Exigir espaço após `#`
`document-start`	Exigir `---` no início	Desabilitar (opcional)
`trailing-spaces`	Sem espaços à direita	Habilitar
`new-line-at-end-of-file`	Final de arquivo consistente	Habilitar

Erros Comuns Detectados pelo Linting

1. Caracteres Tab

O YAML proíbe tabs para indentação, mas editores às vezes os inserem:

# ERRO: caractere tab
server:
port: 8080  # Tab em vez de espaços!

2. Indentação Inconsistente

# ERRO: misturando indentação de 2 e 4 espaços
database:
  host: localhost
    port: 5432  # Errado: 4 espaços em vez de 2

3. Chaves Duplicadas

# ERRO: chave duplicada (a segunda sobrescreve a primeira silenciosamente)
server:
  port: 8080
  host: localhost
  port: 9090  # Duplicada! Qual porta será usada?

4. Espaços à Direita

Espaços invisíveis no final da linha podem causar comportamentos surpreendentes, especialmente em strings multilinhas. Um linter sinaliza isso imediatamente.

Validação rápida sem instalar nada: cole seu YAML em nosso Validador YAML.

Integração com CI/CD

GitHub Actions

name: YAML Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint YAML files
        run: yamllint .

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.33.0
    hooks:
      - id: yamllint
        args: [-c, .yamllint.yml]

pip install pre-commit
pre-commit install

Agora o YAML é automaticamente verificado antes de cada commit.

GitLab CI

yaml-lint:
  image: python:3.12-slim
  script:
    - pip install yamllint
    - yamllint .
  rules:
    - changes:
        - "**/*.yaml"
        - "**/*.yml"

Integração com Editores

A maioria dos editores suporta linting YAML em tempo real:

VS Code: Instale a extensão "YAML" da Red Hat (usa yamllint)
Vim/Neovim: Use ALE ou coc-yaml
JetBrains IDEs: Suporte YAML integrado com inspeções configuráveis

Habilite a formatação automática ao salvar para arquivos YAML para corrigir automaticamente problemas de espaçamento.

Linting Específico por Ferramenta

O linting genérico de YAML detecta erros de sintaxe, mas linters específicos por ferramenta validam a correção semântica:

Kubernetes

# kubeval - valida contra schemas do K8s
kubeval deployment.yaml

# kubeconform - alternativa mais rápida
kubeconform -strict deployment.yaml

Docker Compose

docker compose config --quiet

GitHub Actions

# actionlint - valida sintaxe de workflows
actionlint .github/workflows/*.yml

Ansible

ansible-lint playbook.yml

Para um entendimento mais aprofundado das regras de sintaxe YAML, veja nosso tutorial de sintaxe YAML.

Resumo das Boas Práticas

Adicione yamllint ao CI — Toda alteração YAML deve passar pelo linting
Use pre-commit hooks — Detecte erros antes de chegarem ao repositório
Padronize a indentação com 2 espaços — A convenção do DevOps
Desabilite ou restrinja a regra truthy — O problema dos booleanos yes/no causa bugs reais
Defina um comprimento de linha razoável — 120 caracteres cobre a maioria dos casos
Use validadores específicos por ferramenta — Linting genérico mais validação específica para K8s/Docker/Actions
Configure seu editor — Feedback em tempo real é mais rápido que falhas no CI

FAQ

Devo usar YAML ou JSON para arquivos de configuração?

YAML é preferível para arquivos de configuração editados por humanos devido à sua legibilidade, suporte a comentários e sintaxe concisa. JSON é melhor para dados gerados por máquinas e comunicação via API. Para uma comparação detalhada, veja nosso guia YAML vs JSON.

Como lidar com avisos vs erros do yamllint?

Configure regras críticas (indentação, sintaxe) como erros que bloqueiam o CI. Defina regras de estilo (comprimento de linha, comentários) como avisos que aparecem mas não bloqueiam. Isso equilibra rigor com produtividade do desenvolvedor.

Recursos Relacionados

Validador YAML — Valide sintaxe YAML online instantaneamente
Tutorial de Sintaxe YAML — Aprenda YAML do zero
YAML para Docker Compose — Padrões YAML específicos para Docker