Skip to main content

Migration Guide

Use this guide to migrate from older Specmatic setup patterns to the current recommended approach.

1. Migrate to the unified enterprise artifact​

Move from protocol-specific legacy artifacts/images to the unified Specmatic Enterprise artifact and image.

This covers:

  1. Legacy-to-new artifact mapping
  2. Docker image migration to specmatic/enterprise
  3. JUnit interface migration to io.specmatic.enterprise.SpecmaticContractTest

2. Migrate from legacy Insights reporter to direct command reporting​

Legacy build reporter support has been removed. If your CI pipeline still uses either of the integrations below, add Insights options to the specmatic test, specmatic mock, or specmatic run-suite command that generates the report.

The following legacy integrations are no longer supported:

  1. specmatic-insights-build-reporter-github-action
  2. specmatic-insights-github-build-reporter

The GitHub Action above internally invoked the GitHub build reporter. Migrate both to direct report submission from the built-in Specmatic command in your CI pipeline.

Why this is better:

  1. One native Specmatic command instead of a separate reporter integration.
  2. CTRF-friendly workflows for standardized test result publishing.
  3. Better looking and more detailed Insights visualization with richer report context.

Recommended sequence:

  1. Start with Central Contract Repository CI setup.
  2. Migrate Spec Metadata Reporting (see subsection below).
  3. Migrate each service build to direct CTRF report submission (see subsection below).

Migrate Spec Metadata Reporting​

Use this when your central contract repository has a dedicated reporting step:

Deprecated command

central-contract-repo-report is deprecated. Use spec-metadata-report instead. The deprecated command remains available as a compatibility alias.

  1. Keep pre-merge checks: spectral lint, specmatic examples validate, and specmatic backward-compatibility-check.
  2. Add specmatic spec-metadata-report on the main branch pipeline to generate the Spec Metadata Report. See Reports Sent to Insights for the payload published from this report.
  3. Run specmatic spec-metadata-report with --ci, --build-id, and repository metadata on main to generate and publish the report.
  4. Keep --ci out of PR/MR validation jobs so non-main runs are not published to Insights.
  5. Start from Central Contract Repository CI setup, then append report generation and publish steps.

Migrate each service build to direct CTRF reporting​

Apply this to every service repository (consumer, BFF/provider, domain service):

  1. Remove deprecated reporter steps/actions from the CI workflow.
  2. Add --ci, --build-id, and repository metadata to the existing specmatic test, specmatic mock, or specmatic run-suite step on the main branch only.
  3. Pass repository metadata (branch-name, repo-name, repo-id, repo-url) from CI environment variables.
  4. Ensure service-account license setup is present before running the command.
  5. Enable CTRF output in your Specmatic reporting configuration.
  6. Publish CTRF artifacts/results in CI as part of the same workflow.

Example migration (GitHub Actions):

# Before (deprecated GitHub Action)
- name: Publish to Insights (deprecated action)
  uses: specmatic/specmatic-insights-build-reporter-github-action@v1
  with:
    org-id: ${{ secrets.SPECMATIC_ORG_ID }}
    branch-name: ${{ github.ref_name }}
    repo-name: ${{ github.event.repository.name }}
    repo-id: ${{ github.repository_id }}
    repo-url: ${{ github.event.repository.html_url }}

# Before (deprecated direct reporter)
- name: Publish to Insights (deprecated reporter)
  run: |
    docker run \
      -v ${{ github.workspace }}:/workspace \
      specmatic/specmatic-insights-github-build-reporter:latest \
        --org-id ${{ secrets.SPECMATIC_ORG_ID }} \
        --branch-name ${{ github.ref_name }} \
        --repo-name ${{ github.event.repository.name }} \
        --repo-id ${{ github.repository_id }} \
        --repo-url ${{ github.event.repository.html_url }}

# After (recommended)
- name: Write specmatic license key to file
  run: |
    mkdir -p ~/.specmatic
    echo "${{ secrets.SPECMATIC_LICENSE_KEY }}" > ~/.specmatic/specmatic-license.txt

- name: Run contract tests and publish to Specmatic Insights
  if: github.ref == 'refs/heads/main'
  run: |
    docker run --rm \
      -v ~/.specmatic:/root/.specmatic \
      -v ${{ github.workspace }}:/usr/src/app \
      specmatic/enterprise \
      test \
      --ci \
      --build-id ${{ github.run_id }} \
      --branch-name ${{ github.ref_name }} \
      --repo-name ${{ github.event.repository.name }} \
      --repo-id ${{ github.repository_id }} \
      --repo-url ${{ github.event.repository.html_url }}

Reference examples:

  1. Insights CI/CD integration examples
  2. Continuous Integration walkthrough for service projects
  3. BFF CTRF workflow examples
  4. CTRF report configuration

3. Migrate configuration from v2 to v3​

Move from provides/consumes-centric configuration to the v3 model with explicit:

  1. systemUnderTest
  2. dependencies.services
  3. Reusable components (sources, services, runOptions)

Reference: