Continuous Integration

Continuous Integration

Specmatic is a platform and programming language independent executable. We can run it in all CI environments through the command line interface.

Objective of this tutorial

By the end of this tutorial, you’ll have CI Pipeline running Specmatic on your:

Central contract repository
API providers
API consumers

Let’s get started!

Architecture Overview

In this tutorial, we’ll be working with a typical scenario of microservices & microfrontends involving a Backend-for-Frontend (BFF) and a Domain Service. Here’s an overview of what we’ll be setting up:

Order Microservices architecture

In this architecture:

The App represents the client application (e.g., a mobile app or web frontend)
The BFF (Backend-for-Frontend) acts as an intermediary, tailoring the API for specific client needs
The Domain Service represents the core business logic and data management

We’ll be working with two OpenAPI specifications:

order_bff.yaml: Implemented by the BFF services, this specification defines the API contract between clients (like the mobile app) and the BFF.
order_api.yaml: Implemented by the Domain Service, this specification defines the API contract between the BFF and the Domain Service.

Step 1: Setting Up a Central Contract Repository

Setup overview

A central contract repository is crucial for maintaining consistency across your API specifications and enabling effective contract testing.

If you already have a central contract repository, you can use that instead and skip to the next section.

Setting up the central contract repository

Create a new Git repository named “api-contracts”.

In this repository, create a folder structure to organize your OpenAPI specifications. For our example, we will do it as follows:

   api-contracts/
   ├── orders/
   │   ├── order_bff.yaml
   │   └── order_api.yaml
   └── other-services/

Download and add the following OpenAPI specifications to the repository as depicted above

CI Pipeline Setup

We need to set up a simple CI pipeline to perform the following actions on OpenAPI specs in the central contract repo:

lint
check backward compatibility of your contracts using Specmatic
generate insights report, using specmatic docker image
publish build reports to specmatic insights

name: Lint specifications, check backward compatibility and generate report

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
jobs:
  run-lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: 'lts'

      - name: Install OpenAPI linter
        run: npm install -g @stoplight/spectral-cli

      - name: Lint OpenAPI specs using Spectral
        run: spectral lint **/*.yaml

      - name: Run OpenAPI Backward Compatibility Check using Specmatic
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/usr/src/app \
            specmatic/specmatic \
            backward-compatibility-check

      - name: Generate central contract repo report
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/usr/src/app \
            specmatic/specmatic \
            central-contract-repo-report

After successfully setting up your central contract repository and running the CI pipeline, you should see output similar to this:

Successful contract repo

Also, you can see our sample central contract repository build report on GitHub

Step 2: Setting up Client, Provider and Domain services

Now that we have our OpenAPI specification checked in, let’s bring our Order services to life!

Client - You can implement the client in the programming language of your choice. Once ready, place the following configuration in a file named specmatic.yaml at the root level of your project. This will:

Virtualize the BFF service for the client application (based on the order_bff.yaml contract), helping to isolate the client.

version: 2
contracts:
  - git:
      url: (your-git-repository)
    consumes:
      - path/to/your/spec/in/git/order_bff.yaml # BFF service contract

BFF Service - Implement the BFF service in the language of your choice. Once ready, place the following configuration in a file named specmatic.yaml at the root level of your project. This will:

Virtualize the Domain API service for the BFF application (based on the order_api.yaml contract)
Test the BFF service as a client (using the order_bff.yaml contract)

version: 2
contracts:
  - git:
      url: (your-git-repository)
    provides:
      - path/to/your/spec/in/git/order_bff.yaml # BFF service contract
    consumes:
      - path/to/your/spec/in/git/order_api.yaml # Domain service contract

Domain Service - After implementing domain service, place the following configuration in a file named specmatic.yaml at the root level of your project. This will test the domain API based on the order_api.yaml contract.

version: 2
contracts:
  - git:
      url: (your-git-repository)
    provides:
      - path/to/your/spec/in/git/order_api.yaml # Domain service contract

Step 2.1: Setting Up CI pipeline for client

After the client is up and running and checked into a Git repository, you can create the following CI pipeline to:

Build the client app
Virtualize the BFF service using order_bff.yaml and the Specmatic Docker image
Test the client implementation against the virtualized BFF service

(note: we implemented the client in react, so setting up pipeline accordingly)

name: Client CI Build using Specmatic Serivce Virtualization

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Use Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'

    - name: Install dependencies
      run: npm ci

    - name: Run Specmatic stub to virtualize the BFF service
      run: |
        docker run -d \
          -v ${{ github.workspace }}/specmatic.yaml:/usr/src/app/specmatic.yaml \
          -p 8080:8080 \
          specmatic/specmatic stub

        # Wait for the stub to be ready
        sleep 10

    - name: Run component test against the Specmatic stub
      run: npm run test:component
      env:
        STUB_URL: http://localhost:8080

Upon successful execution of the client CI pipeline, you should see output resembling this:

Successful Client CI Pipeline

Also, you can see our sample client build report on GitHub

Step 2.2: Setting up CI pipeline for BFF Service

Make sure the BFF service is checked into a Git repository. Then create the following CI pipeline to:

Build the BFF service
Virtualize the Domain service using order_api.yaml and the Specmatic Docker image
Test the BFF service using order_bff.yaml and the Specmatic Docker image

(note: we implemented the BFF service in Kotlin, so setting up pipeline accordingly)

name: Provider CI Build using Specmatic Contract Test

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
    - uses: actions/checkout@v4
      with:
        submodules: 'true'

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'

    - name: Setup Gradle
      uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

    - name: Validate Gradle wrapper
      uses: gradle/wrapper-validation-action@v1

    - name: Run Specmatic stub to virtualize the Order API service
      run: |
        docker run -d \
          -v ${{ github.workspace }}/specmatic.yaml:/usr/src/app/specmatic.yaml \
          -p 9000:9000 \
          specmatic/specmatic stub

        # Wait for the stub to be ready
        sleep 10

    - name: Start Spring Boot application
      run: ./gradlew bootRun &

    - name: Wait for application to start
      run: sleep 30

    - name: Contract Test BFF service using Specmatic
      run: |
        docker run \
          -v ./specmatic.yaml:/usr/src/app/specmatic.yaml \
          --network=host \
          specmatic/specmatic \
          test \
          --port=8080 \
          --host=localhost

After running the BFF service CI pipeline, you should see results similar to:

Successful BFF CI pipeline

Also, you can see our sample BFF build report on GitHub

Step 2.3: Setting up CI pipeline for Order API

Make sure Order Domain API service is checked in to a git repository. Then create the following CI pipeline to :

build the Domain API service
test Domain API service using order_api.yaml and Specmatic docker image.

(note: we implemented the Order Domain API service in Kotlin, so setting up pipeline accordingly)

name: Domain API service CI Build using Specmatic Contract Test

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
    - uses: actions/checkout@v4
      with:
        submodules: 'true'

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '21'
        distribution: 'temurin'

    - name: Setup Gradle
      uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

    - name: Validate Gradle wrapper
      uses: gradle/wrapper-validation-action@v1

    - name: Start Spring Boot application
      run: ./gradlew bootRun &

    - name: Wait for application to start
      run: sleep 30

    - name: Contract Test Domain API service using Specmatic
      run: docker run -v "./specmatic.yaml:/usr/src/app/specmatic.yaml" -e HOST_NETWORK=host --network=host "specmatic/specmatic" test --port=9000 --host=localhost

Upon completion of the Order API CI pipeline, you should see output like this:

Success Order API CI pipeline

Also, you can see our sample Order API build report on GitHub

Summary of Progress

Congratulations! At this point, you have successfully set up and configured:

✅ Central contract repository with CI/CD for linting and backward compatibility checks
✅ Client application with CI/CD for building and testing against a virtualized BFF service
✅ BFF service with CI/CD for building, testing against a virtualized Domain service, and being tested as a provider
✅ Domain service with CI/CD for building and being tested as a provider

All four components are now integrated with Specmatic for contract testing and service virtualization. This setup ensures that your entire API ecosystem is continuously validated and maintains consistency across all services. With this foundation in place, you can now move on to configuring Specmatic Insights to visualize and analyze your API ecosystem.

Step 3: Visualizing Your API Ecosystem

If you are interested to:

View your service dependency graph in real-time as your CI builds run
Track CDD (Contract-Driven Development) adoption progress in your organization
Identify dependencies between services
Monitor API coverage and stub usage of your services

Please go through the detailed Specmatic Insights guide to integrate Specmatic Insights in your CI/CD pipelines.

Cloning API specifications from authenticated Central Contract Repositories

Specmatic requires appropriate auth setup in order to pull the latest API specifications to be used for both Contract Tests and Intelligent Service Virtualization. Here are the details.

Authentication params in Git Repo URI

This approach works across any CI setup which can include the auth params as part of the URI. Simply include your auth params (username/password, PAT and any other access tokens) as env variables (be sure to mask the values for security). Here is an example of Git repo URI in the Specmatic configuration file in this approach.

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://${TOKEN}@github.com/specmatic/central-contract-repo-private.git"
      },
      "provides": [
        "io/specmatic/examples/store/openapi/api_order_v3.yaml"
      ]
    }
  ]
}

version: 2
contracts:
  - git:
      url: https://${TOKEN}@github.com/specmatic/central-contract-repo-private.git
    provides:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml

As long as the env variables are available in the CI build machine (in this example TOKEN), Specmatic will evaluate them and execute Git clone on the fully evaluated URL.

A quick test to see if your Git Repo URI is correct will be to run a command line Git clone in your CI pipeline with it. If it works with command line Specmatic will also be able to use the same to clone your central contract repo to the CI build machine. Here are detailed examples.

GitLab

Examples:

CI_JOB_TOKEN - https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/contract-testing/central-contract-repo.git/
Username / Password - https://${USERNAME}:${PASSWORD}@gitlab.com/contract-testing/central-contract-repo.git/

GitHub Actions

Examples:

Personal Access Token - https://${CENTRAL_CONTRACT_REPO_PAT}@github.com/specmatic/central-contract-repo-private.git

Detailed steps

Set up a Personal Access Token in GitHub with “Read” access for contents on your Central Contract Repository (we recommend using fine-grained tokens)
Add this PAT as a repo secret in your repository where Specmatic Contract Test / and or Service Virtualization is used. Example: CENTRAL_CONTRACT_REPO_ACCESS_TOKEN=<your PAT>
In your GitHub workflow file, for steps involving Specmatic Contract Test and / or Service Virtualization, setup env variable CENTRAL_CONTRACT_REPO_PAT and set its value to the secret that we added above. Example: CENTRAL_CONTRACT_REPO_PAT: ${{ secrets.CENTRAL_CONTRACT_REPO_ACCESS_TOKEN }}. Here is a complete snippet.

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://${CENTRAL_CONTRACT_REPO_PAT}@github.com/specmatic/central-contract-repo-private.git"
      },
      "provides": [
        "io/specmatic/examples/store/openapi/api_order_v3.yaml"
      ]
    }
  ]
}

version: 2
contracts:
  - git:
      url: https://${CENTRAL_CONTRACT_REPO_PAT}@@github.com/specmatic/central-contract-repo-private.git
    provides:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml

GitHub Actions

Note: We are in the process of standardising on a uniform approach (Authentication params in Git Repo URI) across GitHub, GitLab, Azure and more. We suggest considering the steps listed here before going ahead with below technique. Below approach will also continue to be supported.

Set up a Personal Access Token in GitHub with “Read” access for contents on your Central Contract Repository (we recommend using fine-grained tokens)
Add this PAT as a repo secret in your repository where Specmatic Contract Test / and or Service Virtualization is used. Example: CENTRAL_CONTRACT_REPO_ACCESS_TOKEN=<your PAT>
In your GitHub workflow file, for steps involving Specmatic Contract Test and / or Service Virtualization, setup env variable PERSONAL_ACCESS_TOKEN and set its value to the secret that we added above. Example: PERSONAL_ACCESS_TOKEN: ${{ secrets.CENTRAL_CONTRACT_REPO_ACCESS_TOKEN }}. Here is a complete snippet.

    - name: Build with Maven
      working-directory: main
      env:
        PERSONAL_ACCESS_TOKEN: ${{ secrets.CENTRAL_CONTRACT_REPO_ACCESS_TOKEN }}
      run: mvn test package jacoco:report

Then Specmatic automatically detects the presence of PERSONAL_ACCESS_TOKEN env variable and is able to clone the central contract repo to the CI server by leveraging the same.

Continuous Integration

Objective of this tutorial

Architecture Overview

Step 1: Setting Up a Central Contract Repository

Setup overview

Setting up the central contract repository

CI Pipeline Setup

Step 2: Setting up Client, Provider and Domain services

Step 2.1: Setting Up CI pipeline for client

Step 2.2: Setting up CI pipeline for BFF Service

Step 2.3: Setting up CI pipeline for Order API

Summary of Progress

Step 3: Visualizing Your API Ecosystem

Cloning API specifications from authenticated Central Contract Repositories

Authentication params in Git Repo URI

GitLab

GitHub Actions

GitHub Actions

Generic settings for any other CI setup

Featured utilities

GitHub action to set up specmatic environment

Examples