Scalar
Overview

GitLab CI/CD

Basic Pipeline#

Here's a simple pipeline that validates and uploads an OpenAPI document to Scalar:

stages:
  - validate
  - deploy
 
validate_openapi:
  stage: validate
  image: node:20
  script:
    - npx @scalar/cli document validate api/openapi.json
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 
push_to_scalar_registry:
  stage: deploy
  image: node:20
  script:
    - npx @scalar/cli auth login --token $SCALAR_API_KEY
    - npx @scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  needs:
    - validate_openapi

Environment-Based Deployment#

For projects that need different environments (development, staging, production), you can use environment-specific variables:

stages:
  - validate
  - deploy
 
validate_openapi:
  stage: validate
  image: node:20
  script:
    - npx @scalar/cli document validate api/openapi.json
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - api/**/*.yaml
    - if: $CI_COMMIT_BRANCH == "development"
      changes:
        - api/**/*.yaml
 
deploy_production:
  stage: deploy
  image: node:20
  environment:
    name: production
  script:
    - npx @scalar/cli auth login --token $SCALAR_API_KEY
    - npx @scalar/cli registry publish --namespace $SCALAR_NAMESPACE_PRODUCTION --slug your-api api/openapi.json
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  needs:
    - validate_openapi
 
deploy_development:
  stage: deploy
  image: node:20
  environment:
    name: development
  script:
    - npx @scalar/cli auth login --token $SCALAR_API_KEY
    - npx @scalar/cli registry publish --namespace $SCALAR_NAMESPACE_DEVELOPMENT --slug your-api api/openapi.json
  rules:
    - if: $CI_COMMIT_BRANCH == "development"
  needs:
    - validate_openapi

Merge Request Validation#

For teams that want to validate OpenAPI documents before merging:

validate_merge_request:
  stage: validate
  image: node:20
  script:
    - npx @scalar/cli document validate api/openapi.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - api/**

Multi-API Repository#

For repositories containing multiple APIs using parallel jobs:

stages:
  - validate
  - deploy
 
.validate_template: &validate_template
  stage: validate
  image: node:20
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - apis/**
 
.deploy_template: &deploy_template
  stage: deploy
  image: node:20
  before_script:
    - npx @scalar/cli auth login --token $SCALAR_API_KEY
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 
validate_user_api:
  <<: *validate_template
  script:
    - npx @scalar/cli document validate apis/user-api/openapi.json
 
validate_product_api:
  <<: *validate_template
  script:
    - npx @scalar/cli document validate apis/product-api/openapi.json
 
validate_order_api:
  <<: *validate_template
  script:
    - npx @scalar/cli document validate apis/order-api/openapi.json
 
deploy_user_api:
  <<: *deploy_template
  script:
    - npx @scalar/cli registry publish --namespace $SCALAR_NAMESPACE --slug user-api apis/user-api/openapi.json
  needs:
    - validate_user_api
 
deploy_product_api:
  <<: *deploy_template
  script:
    - npx @scalar/cli registry publish --namespace $SCALAR_NAMESPACE --slug product-api apis/product-api/openapi.json
  needs:
    - validate_product_api
 
deploy_order_api:
  <<: *deploy_template
  script:
    - npx @scalar/cli registry publish --namespace $SCALAR_NAMESPACE --slug order-api apis/order-api/openapi.json
  needs:
    - validate_order_api

Using Matrix Jobs (Alternative for Multi-API)#

GitLab also supports parallel matrix jobs for cleaner configuration:

stages:
  - validate
  - deploy
 
validate_apis:
  stage: validate
  image: node:20
  parallel:
    matrix:
      - API_NAME: "user-api"
        API_FILE: "apis/user-api/openapi.json"
      - API_NAME: "product-api"
        API_FILE: "apis/product-api/openapi.json"
      - API_NAME: "order-api"
        API_FILE: "apis/order-api/openapi.json"
  script:
    - npx @scalar/cli document validate "$API_FILE"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - apis/**
 
deploy_apis:
  stage: deploy
  image: node:20
  parallel:
    matrix:
      - API_NAME: "user-api"
        API_FILE: "apis/user-api/openapi.json"
        API_SLUG: "user-api"
      - API_NAME: "product-api"
        API_FILE: "apis/product-api/openapi.json"
        API_SLUG: "product-api"
      - API_NAME: "order-api"
        API_FILE: "apis/order-api/openapi.json"
        API_SLUG: "order-api"
  script:
    - npx @scalar/cli auth login --token $SCALAR_API_KEY
    - npx @scalar/cli registry publish --namespace $SCALAR_NAMESPACE --slug $API_SLUG "$API_FILE"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  needs:
    - validate_apis

Variables and Secrets#

To set up the required variables in GitLab:

  1. CI/CD Variables: Go to your project's Settings → CI/CD → Variables
  2. Required Variables:

Updated

Was this page helpful?