CI/CD Integration for Spec Previews in Branch-based Workflows

[Apoorva64]

Context

Currently, Microcks allows importing specification files either:

• By direct upload, or
• Through the importer system (e.g., from URLs or repositories).

In many teams, OpenAPI or AsyncAPI specs are versioned alongside the application code:

• The main branch contains the validated and production-ready specs.
• Feature branches often include "preview" or "draft" specs that should be tested in isolation before merging.

gitGraph
    commit id: "Init repo" tag: "v1.0"
    branch feature/new-endpoint
    commit id: "Add preview spec (preview-PR-113)"
    checkout main
    merge feature/new-endpoint tag: "v1.1"

Loading

Problem

When importing preview specs from feature branches, we risk:

• Overwriting the stable production mocks if using the same API name/version.
• Polluting Microcks’ global API catalog with transient, branch-specific versions.

Proposal

Enable or document a first-class integration pattern for branch-based spec previews, where:

1. The CI/CD pipeline (e.g., GitHub Actions, GitLab CI, Jenkins) can automatically import a spec from the branches with the previews
2. The imported API is:
   • Tagged or versioned with the branch name (e.g. my-api:1.2-feature-new-endpoint).
   • Stored in a dedicated “preview” namespace or with an identifiable label.
3. When merged into main, the final import updates the canonical version of the API (e.g. my-api:1.2).
4. Optionally, preview versions can be auto-cleaned when branches are deleted or after a TTL expires.

Trigger

This discussion originates from efforts to integrate Microcks into the To be Continuous ecosystem.
The ongoing integration work at to-be-continuous/microcks raised the need for a way to handle branch-based preview specs in Microcks as part of CI/CD pipelines.

[lbroudoux]

Hum ... 🤔 I have some concerns regarding this ...

0. As a general posture, I would say that it's not up to Microcks to compensate "bad versioning" practices => as soon as a modification is made on a development branch (or elsewhere), a version number must be incremented/changed. Overwriting risks for versioned resources always exist - it's up to your development practices, reviews and ci/cd to set some guardrails.

1. Microcks already provides labels to communicate some metadata information, including the status. When initializing a branch and updating the version of the API spec, you may also need to update labels to communicate status:preview, feature:my-new-feature, or any other necessary information. So that the status of your new version is clearly visible.

2. As we get feedback from people deploying Microcks in large organizations, we tend to think that the "One Microcks instance to rule all the APIs" is not necessarily the best approach. We wrote a guide on Deployment topologies, and the pattern called "Regional instances" seems to handle the use case and concerns you mentioned. I think this composition of multiple Microcks instances with a promotion process for stable APIs is much more flexible, encompasses other needs (such as dissociating public and private APIs), is less fragile in terms of setup, and allows keeping Microcks instances dedicated with a simpler core engine that doesn't try to solve too many organization-related issues.

In a nutshell, I would say that we already have solutions to address this kind of situation, and I am not keen on adding more complexity to address organizational issues. I'd prefer to keep working on keeping Microcks lean and easier to deploy to avoid having people slowed down by deployment problems.

What do you think?

[SebastienDegodez]

Large organizations usually work with separate environments (PROD, QAT, etc.). In such cases, they often prefer to deploy one or more Microcks instances per environment. (With a promotion process).

The highest performing organizations (aligned with DORA metrics) typically rely on the CLI upload command rather than import. This approach supports overrides during merges, similar to GitOps repository practices.
(GitOps Repos -> Pipeline Microcks Importer -> Microcks)
The case Microcks 'import' -> Git Repos, it's more difficult to monitor, I think.

They may also use Review Apps created from pull requests.

But, at the code level, mature organizations generally adopt API versioning (via headers, parameters, or URLs), all validation will be as soon as possible (CI).

I think all the features make it possible to address a wide range of scenarios. I have my own preferences, and perhaps I don't see certain limitations. It's only my opinion !