CLI em CI/CD

A CLI do GuaraCloud funciona em qualquer ambiente de CI/CD que suporte Node.js. Autentique com a variável de ambiente GUARA_API_KEY e use as flags --json ou --quiet para saída programável.

Pré-requisitos

Antes de configurar a integração de CI/CD, você precisa de:

1. Uma chave de API das suas configurações de conta
2. Os slugs do projeto e serviço para o alvo do deployment
3. Node.js 18+ disponível no seu ambiente de CI

GitHub Actions

Deploy básico no push

name: Deploy no GuaraCloud

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: Instalar CLI do GuaraCloud
        run: npm install -g @guaracloud/cli

      - name: Deploy
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: guara deploy --project meu-projeto --service minha-api --json

Deploy com detecção de branch

name: Deploy no GuaraCloud

on:
  push:
    branches: [main, staging]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Instalar CLI do GuaraCloud
        run: npm install -g @guaracloud/cli

      - name: Deploy
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: |
          guara deploy \
            --project meu-projeto \
            --service minha-api \
            --branch ${{ github.ref_name }} \
            --json

Deploy com variáveis de ambiente

name: Deploy com Variáveis de Ambiente

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: Instalar CLI do GuaraCloud
        run: npm install -g @guaracloud/cli

      - name: Definir variáveis de ambiente
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: |
          guara env set \
            DATABASE_URL=${{ secrets.DATABASE_URL }} \
            REDIS_URL=${{ secrets.REDIS_URL }} \
            --project meu-projeto \
            --service minha-api

      - name: Deploy
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: guara deploy --project meu-projeto --service minha-api --json

Rollback em caso de falha

name: Deploy com Rollback

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: Instalar CLI do GuaraCloud
        run: npm install -g @guaracloud/cli

      - name: Obter deployment atual
        id: pre-deploy
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: |
          DEPLOY_ID=$(guara deployments list --project meu-projeto --service minha-api --json | jq -r '.[0].id')
          echo "deployment_id=$DEPLOY_ID" >> "$GITHUB_OUTPUT"

      - name: Deploy
        id: deploy
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: guara deploy --project meu-projeto --service minha-api --json

      - name: Rollback em caso de falha
        if: failure() && steps.deploy.outcome == 'failure'
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: |
          guara rollback \
            --deployment ${{ steps.pre-deploy.outputs.deployment_id }} \
            --project meu-projeto \
            --service minha-api \
            --json

GitLab CI

Deploy básico

deploy:
  image: node:20-alpine
  stage: deploy
  only:
    - main
  script:
    - npm install -g @guaracloud/cli
    - guara deploy --project meu-projeto --service minha-api --json
  variables:
    GUARA_API_KEY: $GUARA_API_KEY

Staging e produção

stages:
  - deploy-staging
  - deploy-production

deploy-staging:
  image: node:20-alpine
  stage: deploy-staging
  only:
    - staging
  script:
    - npm install -g @guaracloud/cli
    - guara deploy --project meu-projeto --service minha-api --branch staging --json
  variables:
    GUARA_API_KEY: $GUARA_API_KEY_STAGING
    GUARA_API_URL: https://api.staging.guaracloud.com

deploy-production:
  image: node:20-alpine
  stage: deploy-production
  only:
    - main
  when: manual
  script:
    - npm install -g @guaracloud/cli
    - guara deploy --project meu-projeto --service minha-api --json
  variables:
    GUARA_API_KEY: $GUARA_API_KEY_PRODUCTION

Referência de variáveis de ambiente

Estas variáveis de ambiente configuram a CLI no modo não interativo:

Variável	Descrição	Obrigatória
GUARA_API_KEY	Chave de API para autenticação	Sim
GUARA_API_URL	Sobrescreve URL base da API (para ambientes de staging)	Não
GUARA_PROJECT	Slug do projeto padrão	Não
GUARA_SERVICE	Slug do serviço padrão	Não

Saída JSON para scripts

Todos os comandos suportam --json para saída legível por máquinas. Isso é útil para extrair valores no seu pipeline:

# Obter ID do deployment
DEPLOY_ID=$(guara deploy --json | jq -r '.id')

# Obter URL do serviço
SERVICE_URL=$(guara services info --json | jq -r '.url')

# Verificar status do deployment
STATUS=$(guara deployments list --json | jq -r '.[0].status')

Saída silenciosa para variáveis de shell

Use --quiet para obter apenas o valor mais relevante:

# Retorna apenas o ID do deployment
DEPLOY_ID=$(guara deploy --quiet)

# Retorna apenas o slug do serviço
SERVICE_SLUG=$(guara services create --name minha-api --build-method dockerfile --port 3000 --quiet)

Boas práticas

1. Use secrets — Armazene GUARA_API_KEY no gerenciador de secrets do seu provedor de CI, nunca nos arquivos de pipeline
2. Fixe a versão da CLI — Use npm install -g @guaracloud/cli@0.1.0 para evitar mudanças inesperadas
3. Use --json para parsing — Sempre use --json quando precisar extrair valores da saída da CLI
4. Especifique --project e --service — Sempre seja explícito no CI; não dependa da presença do .guara.json
5. Separe chaves de staging e produção — Use chaves de API diferentes para ambientes de staging e produção
6. Faça cache da CLI — No GitHub Actions, faça cache de ~/.npm para acelerar o passo de instalação