Pular para o conteúdo principal
Versão: 0.11.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 para a verificação
expected_codeNãoCódigo de saída esperado (padrão: 0)
expected_outputNãoPadrão regex para corresponder à saída

:::info Execução no Host e no Container Verificações personalizadas no nível raiz, de comando e de implementação sempre rodam no host. Para executar uma verificação personalizada dentro de uma imagem de container, coloque depends_on dentro do bloco do runtime container selecionado. :::

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​

Verificações personalizadas no nível do runtime container rodam dentro do container:

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

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​