GitLab CI Integration
Integrate LOX backups into your GitLab CI/CD pipelines. Create automatic backups before deployments, after migrations, or on schedule.
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
- masterConfiguration
CI/CD Variables
Configure these variables in Settings → CI/CD → Variables:
| Variable | Type | Description |
|---|---|---|
| LOX_API_KEY | Masked | Your LOX API key (required) |
| LOX_API_URL | Optional | Custom API URL (default: https://backlox.com/api) |
| BACKUP_RETENTION | Optional | Days 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
| Command | Description |
|---|---|
| lox backup create | Create a new backup |
| lox backup list | List recent backups |
| lox backup status <id> | Check backup status |
| lox backup download <id> | Download a backup |
| lox storage info | Show 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: productionScheduled 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:
- mainMulti-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: manualBackup 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:
- tagsBackup 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:
- mainUsing 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 /dataPredefined Variables
Useful GitLab CI variables for backup naming:
| Variable | Example | Description |
|---|---|---|
| $CI_PROJECT_NAME | my-app | Project name |
| $CI_COMMIT_SHORT_SHA | a1b2c3d4 | Short commit hash |
| $CI_COMMIT_REF_NAME | main | Branch or tag name |
| $CI_PIPELINE_ID | 123456 | Pipeline ID |
| $CI_ENVIRONMENT_NAME | production | Environment name |
| $CI_JOB_STARTED_AT | 2024-01-15T03:00:00Z | Job 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_failureTroubleshooting
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.