CLI in CI/CD

The GuaraCloud CLI works in any CI/CD environment that supports Node.js. Authenticate with the GUARA_API_KEY environment variable and use --json or --quiet flags for scriptable output.

Prerequisites

Before setting up CI/CD integration, you need:

An API key from your account settings
The project and service slugs for your deployment target
Node.js 18+ available in your CI environment

GitHub Actions

Basic deployment on push

name: Deploy to 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: Install GuaraCloud CLI
        run: npm install -g @guaracloud/cli

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

Deploy with branch detection

name: Deploy to 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: Install GuaraCloud CLI
        run: npm install -g @guaracloud/cli

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

Deploy with environment variables from file

name: Deploy with Env Vars

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

      - name: Set environment variables
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: |
          guara env set \
            DATABASE_URL=${{ secrets.DATABASE_URL }} \
            REDIS_URL=${{ secrets.REDIS_URL }} \
            --project my-project \
            --service my-api

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

Rollback on failure

name: Deploy with 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: Install GuaraCloud CLI
        run: npm install -g @guaracloud/cli

      - name: Get current deployment
        id: pre-deploy
        env:
          GUARA_API_KEY: ${{ secrets.GUARA_API_KEY }}
        run: |
          DEPLOY_ID=$(guara deployments list --project my-project --service my-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 my-project --service my-api --json

      - name: Rollback on failure
        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 my-project \
            --service my-api \
            --json

GitLab CI

Basic deployment

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

Staging and production

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 my-project --service my-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 my-project --service my-api --json
  variables:
    GUARA_API_KEY: $GUARA_API_KEY_PRODUCTION

Environment variables reference

These environment variables configure the CLI in non-interactive mode:

Variable	Description	Required
`GUARA_API_KEY`	API key for authentication	Yes
`GUARA_API_URL`	Override API base URL (for staging environments)	No
`GUARA_PROJECT`	Default project slug	No
`GUARA_SERVICE`	Default service slug	No

JSON output for scripting

All commands support --json for machine-readable output. This is useful for extracting values in your pipeline:

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

# Get service URL
SERVICE_URL=$(guara services info --json | jq -r '.url')

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

Quiet output for shell variables

Use --quiet to get the single most relevant value:

# Returns only the deployment ID
DEPLOY_ID=$(guara deploy --quiet)

# Returns only the service slug
SERVICE_SLUG=$(guara services create --name my-api --build-method dockerfile --port 3000 --quiet)

Best practices

Use secrets — Store GUARA_API_KEY in your CI provider’s secrets manager, never in pipeline files
Pin the CLI version — Use npm install -g @guaracloud/cli@0.1.0 to avoid unexpected changes
Use --json for parsing — Always use --json when you need to extract values from CLI output
Specify --project and --service — Always be explicit in CI; do not rely on .guara.json being present
Separate staging and production keys — Use different API keys for staging and production environments
Cache the CLI — In GitHub Actions, cache ~/.npm to speed up the install step