GitLab CI/CD Integration¶

This guide shows you how to configure GitLab CI/CD pipelines to automatically deploy your Airbase applications:

• Automatic production deployment: Deploy to production when code is merged to the main branch
• Preview environments: Automatically deploy merge requests to isolated preview environments
• GitLab environments integration: "View Deployment" buttons appear on merge requests
• Automatic cleanup: Preview environments are destroyed when merge requests are closed or merged

Prerequisites¶

• An Airbase project created in Console (note your team/project handle)
• Access to SGTS GitLab (Singapore Government GitLab instance)
• Repository permissions to configure CI/CD variables and .gitlab-ci.yml

Step 1: Generate Airbase Credentials¶

Create credentials for use in your CI/CD pipeline:

1. Go to Airbase Console
2. Navigate to Settings → Credentials
3. Click Generate Credentials
4. Copy the generated credentials (you'll need them in Step 2)

The credentials will look like:

AIRBASE_ACCESS_KEY_ID=xxx
AIRBASE_SECRET_ACCESS_KEY=yyy

Step 2: Configure GitLab CI/CD Variables¶

Add the following CI/CD variables in your GitLab project:

Navigate to: Your GitLab project → Settings → CI/CD → Variables

Required Variables¶

airbase configure

Application Environment Variables¶

Environment variables required by your application should be configured as CI/CD variables, not checked into your repository.

Step 3: Configure GitLab CI Pipeline¶

Add these lines to your .gitlab-ci.yml file to enable GitLab CI pipelines using the recommended Airbase template:

include:
  - project: innersource/sgts/runtime/airbase/airbase-pipeline
    ref: v1
    file: baseline.gitlab-ci.yml

review:
  extends: .airbase-deploy
  stage: test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    AIRBASE_ENVIRONMENT: $CI_COMMIT_REF_SLUG
  environment:
    name: review/$AIRBASE_ENVIRONMENT
    deployment_tier: testing
    url: $DYNAMIC_ENVIRONMENT_URL
    on_stop: stop_review
    auto_stop_in: 1 day

stop_review:
  extends: .airbase-destroy
  stage: test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  needs:
    - review
  variables:
    AIRBASE_ENVIRONMENT: $CI_COMMIT_REF_SLUG
  environment:
    name: review/$AIRBASE_ENVIRONMENT
    deployment_tier: testing
    action: stop

production:
  extends: .airbase-deploy
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  variables:
    AIRBASE_ENVIRONMENT: default
  environment:
    name: production
    deployment_tier: staging
    url: $DYNAMIC_ENVIRONMENT_URL
    on_stop: stop_production

stop_production:
  extends: .airbase-destroy
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  needs:
    - production
  variables:
    AIRBASE_ENVIRONMENT: default
  environment:
    name: production
    deployment_tier: staging
    action: stop

Pipeline Configuration Explained¶

Review environment (merge requests): - Triggers on merge request creation - Deploys to a branch-specific environment ($CI_COMMIT_REF_SLUG) - Automatically stops after 1 day - Destroyed when merge request is closed/merged

Production environment (main branch): - Triggers on commits to main branch - Deploys to production (default environment) - Requires manual action to stop

Step 4: Verify Your Setup¶

After committing the .gitlab-ci.yml file:

1. Test merge request deployment:
2. Create a new branch and make changes
3. Open a merge request
4. Wait for pipeline to complete

5. Click View Deployment button on merge request

6. View all environments:

7. Go to Operate → Environments in GitLab

8. You should see all branch environments and production

9. Test production deployment:

10. Merge your changes to main branch
11. Check that production pipeline runs
12. Verify deployment at your production URL

Troubleshooting¶

Pipeline fails with "Authentication failed"¶

Cause: Incorrect or missing Airbase credentials

Solution: - Verify AIRBASE_RC variable contains valid credentials - Check credentials haven't expired (regenerate in Console if needed) - Ensure variable type is set to "File" not "Variable"

"Project not found" error¶

Cause: Incorrect project handle (applies to legacy AIRBASE_PROJECT_HANDLE setup)

Solution:

If using airbase.json (recommended): - Verify airbase.json exists in your repository root - Check that the handle field is correct: "handle": "team/project" - Ensure airbase.json is committed to your repository

If using legacy AIRBASE_PROJECT_HANDLE: - Verify AIRBASE_PROJECT_HANDLE matches exactly: team/project - Check spelling and case sensitivity - Confirm project exists in Airbase Console - Consider migrating to airbase.json by running airbase configure

Environment variables not loaded in application¶

Cause: AIRBASE_ENV_LOCAL_FILE not configured correctly

Solution: - Verify variable type is set to "File" - Check syntax (KEY=value format, one per line) - Ensure no extra spaces or quotes

Preview environment still running after merge¶

Cause: Auto-cleanup may take a few minutes

Solution: - Wait 5-10 minutes for automatic cleanup - Manually stop environment in GitLab: Operate → Environments → Stop - Or destroy via CLI: airbase container destroy <environment-name>

Environment Scoping¶

You can scope CI/CD variables to specific environments or branches:

Example: Different database URLs per environment

This ensures production uses production databases, while preview environments use staging databases.

See Also¶

• How-To: Manage Environments - Managing environments via CLI
• How-To: Set Environment Variables - Managing environment variables
• Reference: CLI Commands - Full CLI reference