Netlify Deploy

Skill de Deploy no Netlify

Automatize deploys no Netlify usando a Netlify CLI com detecção inteligente de configuração de projeto e contexto de deployment.

Visão Geral

Este skill automatiza deploys no Netlify por:

• Verificar autenticação na Netlify CLI
• Detectar configuração e framework do projeto
• Vincular a sites existentes ou criar novos
• Fazer deploy para ambientes de produção ou preview

Pré-requisitos

• Netlify CLI: Instalada via npx (não requer instalação global)
• Autenticação: Conta Netlify com sessão de login ativa
• Projeto: Projeto web válido no diretório atual
• Quando a sandbox bloqueia chamadas de rede do deployment, execute novamente com sandbox_permissions=require_escalated.
• O deployment pode levar alguns minutos. Use valores de timeout apropriados.

Padrão de Autenticação

O skill usa a abordagem Netlify CLI pré-autenticada:

1. Verificar status de autenticação com npx netlify status
2. Se não autenticado, guiar usuário através de npx netlify login
3. Falhar graciosamente se a autenticação não puder ser estabelecida

A autenticação usa:

• OAuth baseado em navegador (primário): netlify login abre navegador para autenticação
• API Key (alternativa): Defina variável de ambiente NETLIFY_AUTH_TOKEN

Fluxo de Trabalho

1. Verificar Autenticação na Netlify CLI

Verifique se o usuário está logado no Netlify:

npx netlify status

Padrões de saída esperados:

• ✅ Autenticado: Mostra email do usuário logado e status de vinculação do site
• ❌ Não autenticado: "Not logged into any site" ou erro de autenticação

Se não autenticado, guie o usuário:

npx netlify login

Isso abre uma janela do navegador para autenticação OAuth. Aguarde o usuário concluir o login e verifique novamente com netlify status.

Autenticação alternativa: API Key

Se a autenticação do navegador não estiver disponível, usuários podem definir:

export NETLIFY_AUTH_TOKEN=seu_token_aqui

Tokens podem ser gerados em: https://app.netlify.com/user/applications#personal-access-tokens

2. Detectar Status de Vinculação do Site

A partir da saída de netlify status, determine:

• Vinculado: Site já conectado ao Netlify (mostra nome/URL do site)
• Não vinculado: Precisa vincular ou criar site

3. Vincular a Site Existente ou Criar Novo

Se já vinculado → Vá para passo 4

Se não vinculado, tente vincular pela origem Git:

# Verifique se o projeto é baseado em Git
git remote show origin

# Se baseado em Git, extraia URL remota
# Formato: https://github.com/usuario/repo ou git@github.com:usuario/repo.git

# Tente vincular pela origem Git
npx netlify link --git-remote-url <URL_REMOTA>

Se a vinculação falhar (site não existe no Netlify):

# Criar novo site interativamente
npx netlify init

Isso guia o usuário através de:

1. Escolha de time/conta
2. Definição de nome do site
3. Configuração de settings de build
4. Criação de netlify.toml se necessário

4. Verificar Dependências

Antes de fazer deploy, garanta que as dependências do projeto estão instaladas:

# Para projetos npm
npm install

# Para outros gerenciadores de pacotes, detecte e use comando apropriado
# yarn install, pnpm install, etc.

5. Deploy para Netlify

Escolha tipo de deployment baseado no contexto:

Deploy de Preview/Rascunho (padrão para sites existentes):

npx netlify deploy

Isso cria um deploy preview com URL única para testes.

Deploy de Produção (para novos sites ou deploys de produção explícitos):

npx netlify deploy --prod

Isso faz deploy para a URL de produção ativa.

Processo de deployment:

1. CLI detecta settings de build (de netlify.toml ou solicita ao usuário)
2. Compila o projeto localmente
3. Envia assets compilados ao Netlify
4. Retorna URL do deployment

6. Relatar Resultados

Após deployment, reporte ao usuário:

• URL de Deploy: URL única para este deployment
• URL do Site: URL de produção (se deployment de produção)
• Logs de Deploy: Link para dashboard do Netlify para logs
• Próximos passos: Sugira netlify open para visualizar site ou dashboard

Tratamento de netlify.toml

Se um arquivo netlify.toml existir, a CLI o usará automaticamente. Se não, a CLI solicitará:

• Comando de build: ex., npm run build, next build
• Diretório de publicação: ex., dist, build, .next

Padrões comuns de framework:

• Next.js: comando de build npm run build, publicar .next
• React (Vite): comando de build npm run build, publicar dist
• HTML Estático: sem comando de build, publicar diretório atual

O skill deve detectar framework a partir de package.json se possível e sugerir settings apropriadas.

Exemplo de Fluxo Completo

# 1. Verificar autenticação
npx netlify status

# Se não autenticado:
npx netlify login

# 2. Vincular site (se necessário)
# Tente vinculação baseada em Git primeiro
git remote show origin
npx netlify link --git-remote-url https://github.com/usuario/repo

# Se nenhum site existe, criar novo:
npx netlify init

# 3. Instalar dependências
npm install

# 4. Deploy (preview para teste)
npx netlify deploy

# 5. Deploy para produção (quando pronto)
npx netlify deploy --prod

Tratamento de Erros

Problemas comuns e soluções:

"Not logged in" → Execute npx netlify login

"No site linked" → Execute npx netlify link ou npx netlify init

"Build failed" → Verifique comando de build e diretório de publicação em netlify.toml ou prompts da CLI → Verifique se dependências estão instaladas → Revise logs de build para erros específicos

"Publish directory not found" → Verifique se comando de build executou com sucesso → Verifique se caminho do diretório de publicação está correto

Solução de Problemas

Acesso de Rede Escalado

Se o deployment falhar por problemas de rede (timeouts, erros DNS, reset de conexão), execute novamente o deploy com permissões escaladas (use sandbox_permissions=require_escalated). O deploy requer acesso de rede escalado quando a sandbox bloqueia requisições de saída.

Exemplo de orientação ao usuário:

O deploy precisa de acesso de rede escalado para fazer deploy no Netlify. Posso executar o comando novamente com permissões escaladas—quer que eu prossiga?

Variáveis de Ambiente

Para secrets e configuração:

1. Nunca faça commit de secrets no Git
2. Defina no dashboard do Netlify: Site Settings → Environment Variables
3. Acesse em builds via process.env.VARIABLE_NAME

Dicas

• Use netlify deploy (sem --prod) primeiro para testar antes de produção
• Execute netlify open para visualizar site no dashboard do Netlify
• Execute netlify logs para visualizar logs de função (se usando Netlify Functions)
• Use netlify dev para desenvolvimento local com Netlify Functions

Referência

• Docs Netlify CLI: https://docs.netlify.com/cli/get-started/
• Referência netlify.toml: https://docs.netlify.com/configure-builds/file-based-configuration/

Referências Agrupadas (Carregue Conforme Necessário)

• CLI commands
• Deployment patterns
• netlify.toml guide