GitLab CI Integration

Integrate LOX backups into your GitLab CI/CD pipelines. Create automatic backups before deployments, after migrations, or on schedule.

v1.0.0Updated 2026-01-01

Quick Start

Add the LOX backup job to your .gitlab-ci.yml:

# .gitlab-ci.yml
stages:
  - backup
  - deploy

backup:
  stage: backup
  image: loxbackup/cli:latest
  script:
    - lox backup create --name "$CI_PROJECT_NAME-$CI_COMMIT_SHORT_SHA"
  variables:
    LOX_API_KEY: $LOX_API_KEY
  only:
    - main
    - master

Configuration

CI/CD Variables

Configure these variables in Settings → CI/CD → Variables:

VariableTypeDescription
LOX_API_KEYMaskedYour LOX API key (required)
LOX_API_URLOptionalCustom API URL (default: https://backlox.com/api)
BACKUP_RETENTIONOptionalDays to retain backups (default: 30)

Security Best Practice

Always mark LOX_API_KEY as Masked and Protectedto prevent exposure in logs and limit access to protected branches.

Available CLI Commands

CommandDescription
lox backup createCreate a new backup
lox backup listList recent backups
lox backup status <id>Check backup status
lox backup download <id>Download a backup
lox storage infoShow storage usage

Pipeline Examples

Pre-Deployment Backup

Create a backup before deploying to production:

stages:
  - test
  - backup
  - deploy

test:
  stage: test
  script:
    - npm ci
    - npm test

backup_production:
  stage: backup
  image: loxbackup/cli:latest
  variables:
    LOX_API_KEY: $LOX_API_KEY
  script:
    - |
      echo "Creating pre-deployment backup..."
      BACKUP_ID=$(lox backup create \
        --name "pre-deploy-$CI_COMMIT_SHORT_SHA" \
        --source "$PRODUCTION_SERVER" \
        --wait \
        --output json | jq -r '.id')
      echo "BACKUP_ID=$BACKUP_ID" >> backup.env
    - lox backup status $BACKUP_ID
  artifacts:
    reports:
      dotenv: backup.env
  only:
    - main
  environment:
    name: production

deploy_production:
  stage: deploy
  script:
    - echo "Deploying with backup $BACKUP_ID available for rollback"
    - ./deploy.sh
  dependencies:
    - backup_production
  only:
    - main
  environment:
    name: production

Scheduled Backups

Use GitLab schedules for regular automated backups:

# Scheduled backup job
scheduled_backup:
  stage: backup
  image: loxbackup/cli:latest
  variables:
    LOX_API_KEY: $LOX_API_KEY
  script:
    - |
      DATE=$(date +%Y%m%d_%H%M%S)
      lox backup create \
        --name "$CI_PROJECT_NAME-scheduled-$DATE" \
        --retention 30 \
        --wait
    - lox backup list --limit 5
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

# Configure schedule in GitLab:
# Settings → CI/CD → Pipeline schedules
# - Daily at 3:00 AM: 0 3 * * *
# - Every 6 hours: 0 */6 * * *

Database Migration Backup

Create a backup before running database migrations:

stages:
  - build
  - backup
  - migrate
  - deploy

build:
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

backup_before_migration:
  stage: backup
  image: loxbackup/cli:latest
  variables:
    LOX_API_KEY: $LOX_API_KEY
  script:
    - |
      lox backup create \
        --name "pre-migration-$CI_COMMIT_SHORT_SHA" \
        --source "$DB_HOST" \
        --type database \
        --wait
  only:
    - main
  when: manual
  allow_failure: false

run_migrations:
  stage: migrate
  image: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  script:
    - npm run db:migrate
  needs:
    - backup_before_migration
  only:
    - main

deploy:
  stage: deploy
  script:
    - kubectl set image deployment/app app=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  needs:
    - run_migrations
  only:
    - main

Multi-Environment Backups

.backup_template: &backup_template
  image: loxbackup/cli:latest
  variables:
    LOX_API_KEY: $LOX_API_KEY
  script:
    - |
      lox backup create \
        --name "$CI_PROJECT_NAME-$CI_ENVIRONMENT_NAME-$CI_COMMIT_SHORT_SHA" \
        --wait
    - lox backup list --limit 3

backup_staging:
  <<: *backup_template
  stage: backup
  environment:
    name: staging
  only:
    - develop

backup_production:
  <<: *backup_template
  stage: backup
  environment:
    name: production
  only:
    - main
  when: manual

Backup with File Upload

Backup files from the CI environment:

backup_artifacts:
  stage: backup
  image: loxbackup/cli:latest
  variables:
    LOX_API_KEY: $LOX_API_KEY
  script:
    # Create archive of build artifacts
    - tar -czf artifacts.tar.gz dist/ build/ public/

    # Upload to LOX
    - |
      lox backup upload artifacts.tar.gz \
        --name "build-artifacts-$CI_COMMIT_SHORT_SHA" \
        --metadata "commit=$CI_COMMIT_SHA" \
        --metadata "pipeline=$CI_PIPELINE_ID"
  artifacts:
    paths:
      - dist/
      - build/
    expire_in: 1 week
  only:
    - tags

Backup Verification

backup_and_verify:
  stage: backup
  image: loxbackup/cli:latest
  variables:
    LOX_API_KEY: $LOX_API_KEY
  script:
    # Create backup
    - |
      BACKUP_ID=$(lox backup create \
        --name "verified-$CI_COMMIT_SHORT_SHA" \
        --wait \
        --output json | jq -r '.id')

    # Verify backup integrity
    - lox backup verify $BACKUP_ID

    # Check backup size
    - |
      SIZE=$(lox backup status $BACKUP_ID --output json | jq -r '.size_bytes')
      if [ "$SIZE" -lt 1000 ]; then
        echo "Warning: Backup seems too small ($SIZE bytes)"
        exit 1
      fi

    - echo "Backup $BACKUP_ID verified successfully"
  only:
    - main

Using Docker-in-Docker

For complex backup scenarios with Docker:

backup_with_docker:
  stage: backup
  image: docker:latest
  services:
    - docker:dind
  variables:
    LOX_API_KEY: $LOX_API_KEY
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker pull loxbackup/cli:latest
  script:
    - |
      docker run --rm \
        -e LOX_API_KEY=$LOX_API_KEY \
        -v $(pwd):/data:ro \
        loxbackup/cli:latest \
        backup create --name "docker-backup-$CI_COMMIT_SHORT_SHA" --path /data

Predefined Variables

Useful GitLab CI variables for backup naming:

VariableExampleDescription
$CI_PROJECT_NAMEmy-appProject name
$CI_COMMIT_SHORT_SHAa1b2c3d4Short commit hash
$CI_COMMIT_REF_NAMEmainBranch or tag name
$CI_PIPELINE_ID123456Pipeline ID
$CI_ENVIRONMENT_NAMEproductionEnvironment name
$CI_JOB_STARTED_AT2024-01-15T03:00:00ZJob start timestamp

Error Handling

backup_with_retry:
  stage: backup
  image: loxbackup/cli:latest
  variables:
    LOX_API_KEY: $LOX_API_KEY
  script:
    - |
      MAX_RETRIES=3
      RETRY_COUNT=0

      until lox backup create --name "backup-$CI_COMMIT_SHORT_SHA" --wait; do
        RETRY_COUNT=$((RETRY_COUNT + 1))
        if [ $RETRY_COUNT -ge $MAX_RETRIES ]; then
          echo "Backup failed after $MAX_RETRIES attempts"
          exit 1
        fi
        echo "Backup failed, retrying in 30 seconds... (attempt $RETRY_COUNT/$MAX_RETRIES)"
        sleep 30
      done
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

Troubleshooting

Authentication failed

Verify LOX_API_KEY is set in CI/CD variables and the variable is not restricted to protected branches if running on feature branches.

Job timeout

Large backups may exceed the default job timeout. Increase it with timeout: 2h in your job definition.

Variable not found in logs

Masked variables won't appear in logs. Use lox auth status to verify authentication.

Debug mode

Enable verbose output with lox --verbose backup create or set CI_DEBUG_TRACE: "true" for full pipeline debugging.