Pular para o conteúdo principal
Versão: 0.4.0

Dependências de Verificações Personalizadas

Verificações personalizadas permitem que você escreva scripts de validação para requisitos que não se encaixam nos tipos de dependência embutidos. Verifique versões de ferramentas, validade de configuração ou qualquer outro requisito personalizado.

Uso Básico​

depends_on: {
    custom_checks: [
        {
            alternatives: [{
                name: "docker-running"
                check_script: "docker info > /dev/null 2>&1"
            }]
        }
    ]
}

Se a verificação falhar:

✗ Dependencies not satisfied

Command 'build' has unmet dependencies:

Failed Custom Checks:
  • go-version - check script returned non-zero exit code

Ensure all requirements are met and try again.

Propriedades da Verificação​

PropriedadeObrigatóriaDescrição
nameSimIdentificador para mensagens de erro
check_scriptSimScript a executar (usando o shell do runtime selecionado)
expected_codeNãoCódigo de saída esperado (padrão: 0)
expected_outputNãoPadrão regex para corresponder à saída
Execução Consciente do Runtime

Scripts de verificação personalizados são executados usando o shell do runtime: o shell do host para runtime native, o interpretador sh embutido para runtime virtual, ou o shell do container para runtime container. Escreva seu check_script de acordo — por exemplo, uma verificação native pode depender de ferramentas específicas do host, enquanto uma verificação container só enxerga o que está dentro do container.

Validação de Código de Saída​

Por padrão, uma verificação passa se o script sair com código 0:

custom_checks: [
    {
        name: "docker-running"
        check_script: "docker info > /dev/null 2>&1"
        // Passes if exit code is 0
    }
]

Espere um código de saída diferente:

custom_checks: [
    {
        name: "not-production"
        check_script: "test "$ENV" = 'production'"
        expected_code: 1  // Should fail (not be production)
    }
]

Validação de Saída​

Verifique se a saída corresponde a um padrão:

custom_checks: [
    {
        name: "node-version"
        check_script: "node --version"
        expected_output: "^v(18|20|22)."  // Major version 18, 20, or 22
    }
]

Ambas as condições devem passar quando usadas juntas:

custom_checks: [
    {
        name: "go-version"
        check_script: "go version"
        expected_code: 0  // Must succeed
        expected_output: "go1.2[6-9]"  // Must be Go 1.26+
    }
]

Alternativas (Semântica OU)​

Forneça verificações alternativas:

custom_checks: [
    {
        alternatives: [
            {
                name: "go-1.26"
                check_script: "go version | grep -q 'go1.26'"
            },
            {
                name: "go-1.27"
                check_script: "go version | grep -q 'go1.27'"
            }
        ]
    }
]

A dependência é satisfeita se qualquer alternativa passar.

Exemplos do Mundo Real​

Verificação de Versão de Ferramenta​

{
    name: "build"
    depends_on: {
        tools: [{alternatives: ["go"]}]
        custom_checks: [
            {
                name: "go-1.26-or-higher"
                check_script: """
                    version=$(go version | grep -oE 'go[0-9]+.[0-9]+' | head -1)
                    major=$(echo $version | cut -d. -f1 | tr -d 'go')
                    minor=$(echo $version | cut -d. -f2)
                    [ "$major" -ge 1 ] && [ "$minor" -ge 26 ]
                    """
            }
        ]
    }
    implementations: [...]
}

Verificação de Docker Rodando​

{
    name: "docker-build"
    depends_on: {
        tools: [{alternatives: ["docker"]}]
        custom_checks: [
            {
                name: "docker-daemon"
                check_script: "docker info > /dev/null 2>&1"
            }
        ]
    }
    implementations: [{
        script: "docker build -t myapp ."
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Verificação de Status do Git​

{
    name: "release"
    depends_on: {
        tools: [{alternatives: ["git"]}]
        custom_checks: [
            {
                name: "clean-working-tree"
                check_script: "test -z "$(git status --porcelain)""
            },
            {
                name: "on-main-branch"
                check_script: "test "$(git branch --show-current)" = 'main'"
            }
        ]
    }
    implementations: [{
        script: "./scripts/release.sh"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Validação de Configuração​

{
    name: "deploy"
    depends_on: {
        filepaths: [{alternatives: ["config.yaml"]}]
        custom_checks: [
            {
                name: "valid-yaml"
                check_script: "python3 -c 'import yaml; yaml.safe_load(open("config.yaml"))'"
            },
            {
                name: "has-required-fields"
                check_script: """
                    grep -q 'database:' config.yaml && 
                    grep -q 'server:' config.yaml
                    """
            }
        ]
    }
    implementations: [...]
}

Verificação de Memória/Recursos​

{
    name: "build heavy"
    depends_on: {
        custom_checks: [
            {
                name: "enough-memory"
                check_script: """
                    # Check for at least 4GB free memory
                    free_mb=$(free -m | awk '/^Mem:/{print $7}')
                    [ "$free_mb" -ge 4096 ]
                    """
            },
            {
                name: "enough-disk"
                check_script: """
                    # Check for at least 10GB free disk
                    free_gb=$(df -BG . | awk 'NR==2{print $4}' | tr -d 'G')
                    [ "$free_gb" -ge 10 ]
                    """
            }
        ]
    }
    implementations: [...]
}

Contexto do Kubernetes​

{
    name: "deploy"
    depends_on: {
        tools: [{alternatives: ["kubectl"]}]
        custom_checks: [
            {
                name: "correct-context"
                check_script: "kubectl config current-context"
                expected_output: "^production-cluster$"
            },
            {
                name: "cluster-reachable"
                check_script: "kubectl cluster-info > /dev/null 2>&1"
            }
        ]
    }
    implementations: [...]
}

Múltiplas Opções de Versão​

{
    name: "build"
    depends_on: {
        custom_checks: [
            {
                alternatives: [
                    {
                        name: "python-3.11"
                        check_script: "python3 --version"
                        expected_output: "^Python 3.11"
                    },
                    {
                        name: "python-3.12"
                        check_script: "python3 --version"
                        expected_output: "^Python 3.12"
                    }
                ]
            }
        ]
    }
    implementations: [...]
}

Contexto de Container​

Para runtime container, verificações personalizadas rodam dentro do container:

{
    name: "build"
    implementations: [{
        script: "npm run build"
        runtimes: [{name: "container", image: "node:20"}]
        platforms: [{name: "linux"}]
        depends_on: {
            custom_checks: [
                {
                    name: "node-version"
                    // This runs INSIDE the container
                    check_script: "node --version"
                    expected_output: "^v20."
                }
            ]
        }
    }]
}

Dicas de Script​

Mantenha Scripts Simples​

// Good - simple and clear
check_script: "go version | grep -q 'go1.26'"

// Avoid - complex and fragile
check_script: """
    set -e
    version=$(go version 2>&1)
    if [ $? -ne 0 ]; then exit 1; fi
    echo "$version" | grep -qE 'go1.(2[6-9]|[3-9][0-9])'
    """

Use Códigos de Saída Apropriados​

// Script should exit 0 for success, non-zero for failure
check_script: """
    if [ -f "required-file" ]; then
        exit 0
    else
        exit 1
    fi
    """

Trate Comandos Faltando​

check_script: "command -v mytools > /dev/null && mytool --check"

Melhores Práticas​

  1. Nomeie verificações claramente: Use nomes descritivos para mensagens de erro
  2. Mantenha scripts simples: Uma verificação, um propósito
  3. Use códigos de saída: Retorne 0 para sucesso, não-zero para falha
  4. Adicione validação de saída: Quando o formato da versão importa
  5. Considere alternativas: Ofereça múltiplas configurações válidas

Próximos Passos​