docs
Configuração

CI/CD

Deploy automático com GitHub e integração com pipelines de CI/CD.

A Veloz suporta deploy automático via integração com GitHub e deploy manual via CLI em qualquer pipeline de CI/CD.

Deploy automático com GitHub

Como funciona

  1. Você conecta seu repositório GitHub à Veloz
  2. A cada git push na branch configurada, a Veloz faz deploy automaticamente
  3. O processo é: push → webhook → build → deploy (zero intervenção)

Configurando

No primeiro veloz deploy, a CLI detecta o repositório Git e vincula o projeto:

cd meu-projeto
veloz deploy
ℹ Repositório detectado: github.com/usuario/meu-projeto
ℹ Branch: main

Para habilitar deploys automáticos, instale o Veloz GitHub App no seu repositório:

  1. Acesse o dashboard da Veloz
  2. Vá em Projeto → Configurações → GitHub
  3. Clique em Conectar GitHub
  4. Autorize o Veloz GitHub App no repositório

Após conectar, todo push na branch configurada dispara um deploy automático.

Branch de deploy

Por padrão, a Veloz faz deploy da branch main. Para alterar:

veloz config set --branch production

Ou no veloz.json:

{
  "services": {
    ".": {
      "branch": "production"
    }
  }
}

Desativando deploy automático

Desative pelo dashboard em Projeto → Configurações → Auto Deploy.

Deploy via CLI (CI/CD genérico)

Para integrar com qualquer sistema de CI/CD, use a CLI com uma API key.

1. Criar API key

veloz apikey create --name "github-actions"

Guarde a chave — ela só é exibida uma vez.

2. Configurar no CI

Adicione VELOZ_API_KEY como secret no seu sistema de CI.

3. Usar no pipeline

A CLI detecta VELOZ_API_KEY automaticamente — sem precisar de veloz login.

GitHub Actions

name: Deploy to Veloz
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 20
 
      - name: Install Veloz CLI
        run: npm install -g onveloz
 
      - name: Deploy
        run: veloz deploy --yes
        env:
          VELOZ_API_KEY: ${{ secrets.VELOZ_API_KEY }}

Output format

Em CI, a CLI detecta o ambiente automaticamente:

  • GitHub Actions (GITHUB_ACTIONS=true): groups colapsáveis, outputs nativos via $GITHUB_OUTPUT
  • Outros CIs (CI=true): texto simples sem cores

Também pode forçar o formato:

veloz deploy --yes --output json       # JSON estruturado
veloz deploy --yes --output plain      # texto sem cores

GitLab CI

deploy:
  image: node:20
  stage: deploy
  only:
    - main
  script:
    - npm install -g onveloz
    - veloz deploy --yes
  variables:
    VELOZ_API_KEY: $VELOZ_API_KEY

Bitbucket Pipelines

pipelines:
  branches:
    main:
      - step:
          name: Deploy to Veloz
          image: node:20
          script:
            - npm install -g onveloz
            - veloz deploy --yes

Monorepo no CI/CD

A CLI detecta todos os serviços a partir do veloz.json:

# Deploy de todos os serviços
veloz deploy --yes
 
# Deploy de um serviço específico (por chave ou nome)
veloz deploy --service web --yes
 
# Deploy de um app por path
veloz deploy --app apps/web --yes

Flag --yes

A flag --yes (ou -y) pula todas as confirmações interativas — obrigatória para CI/CD:

veloz deploy --yes

Sem ela, a CLI pede confirmação manual e trava o pipeline.

Próximos passos