In many organisations, whatever the gateway (webMethods, Kong, Apigee, Azure API Management, MuleSoft or another), promoting an API from staging to production still looks like this: an export from the console, a file passed through a ticket, a manual import by another team, then a few clicks to adjust environment parameters and activate the API. It works, until the day nobody can say which version runs where, or why production differs from staging.

This article describes the chain architecture we put in place to replace that circuit with a versioned pipeline. Our field of proof is webMethods API Gateway, but the architecture does not depend on the vendor. The tools are deliberately classic, the ones already found in most IT departments: GitLab for the code and the review, Jenkins for orchestration, Ansible for execution on the environments. The subject is not the tool, but the discipline around it.

The principle: Git decides, the pipeline executes, the reread proves

Three rules structure the whole chain:

  1. Git is the only source of truth. What is not in Git does not exist. No manual change in a console on the target environments, except a traced emergency procedure.
  2. The pipeline is the only path to an environment. No manual import “just this once”.
  3. Every deployment ends with a check of the actual state. A deployment is successful when the environment has been reread and found to match Git, not when the last command returned 0.

What goes into Git

A repository per API project (or per functional domain, depending on the size of the estate) contains:

  • the API definition: an OpenAPI or WSDL specification, and useful webMethods metadata;
  • a readable description of the policies: authentication, routing, traffic limits, transformations. We do not version technical identifiers, which change from one environment to another;
  • per-environment values: backend endpoints, aliases, parameters. No secret: secrets are referenced by name and read at runtime from a vault (HashiCorp Vault, for example);
  • the target version number per environment: this is the file one changes in order to promote.

With this organisation, a promotion becomes a merge request: the target version for the next environment is changed, a peer reviews it, it is merged.

The role of each tool

GitLab: review and traceability

GitLab holds the repositories, the merge requests and the branch-protection rules. This is where the “four eyes” principle is applied: no change to a production environment without review and approval by a second person. The Git history naturally answers the question “who changed what, when, and who approved it”.

Depending on the context, GitLab CI can also carry the static validation steps (specification lint, file-structure checks), as close as possible to the developer.

Jenkins: orchestration

Jenkins sequences the pipeline steps and holds the gates. It is often already connected to the organisation’s ITSM tools and directories, which makes it a good conductor for regulated environments. A Jenkinsfile versioned in the repository describes:

  • the steps and their order;
  • the environments allowed for each branch;
  • the approval points: manual validation, an ITSM change-number check before production;
  • the identity used: every run is tied to a named user, not to a shared technical account.

Ansible: idempotent execution

Ansible performs the operations on API Gateway through its administration REST API: create or update the API, apply the policies, set the aliases, activate. Its main interest is idempotence: replaying a playbook on an already compliant environment must change nothing. That is also what makes rollback simple: redeploying the previous version is replaying the same playbook with the old version.

The administration API has its peculiarities (wrapped responses, encoded aliases, 200 codes that guarantee nothing). We have detailed them in webMethods 10.15: pitfalls of the administration REST API. The Ansible layer must absorb them, not ignore them.

The pipeline steps

Here is the typical sequence we put in place, to be adapted to the context:

  1. Static validation: the specification is valid, the environment files are complete, no sensitive value appears in clear text.
  2. Compliance check: governance rules are verified before deployment (mandatory authentication, naming conventions, minimum policies). A non-compliant API does not go out: the pipeline refuses, it does not merely report.
  3. Per-environment resolution: technical identifiers are resolved on the target environment, secrets are read from the vault.
  4. Deployment: Ansible applies the configuration. For a new version of an API in service, the new version is deployed alongside the old one rather than in its place.
  5. Reread and comparison: the actual state of the environment is reread, normalised and compared with the expected state. The slightest discrepancy fails the pipeline.
  6. Smoke tests: a few real calls on the deployed API, with the real authentication rules.
  7. Cutover and withdrawal: traffic moves to the new version; the old one is withdrawn only once the new one has been verified.
  8. Trace: the pipeline publishes a report (version, environment, author, approver, result of each check) attached to the change.

The duration of a promotion with this chain depends on the context and is measured once the pipeline is in place.

Rollback in a single command

A rollback that has never been tested does not exist. In this chain, rolling back means putting the previous version back into the environment file, or replaying the pipeline on the previous tag. Because everything is idempotent and verified by a reread, the rollback takes exactly the same path as a normal deployment, with the same checks.

We recommend exercising it deliberately in staging before the chain goes live, then regularly. It is a test scenario in its own right, on the same footing as the nominal deployment and the refusal of a non-compliant API.

The mistakes we see most often

  • Versioning the binary export as the source of truth. The archive is a transport format, not a review format. Nobody reviews a binary diff.
  • Keeping a shared technical account in the CI. Named traceability is lost, and rotating the password becomes a project in itself.
  • Trusting the return code. Without a reread of the final state, a green pipeline proves nothing.
  • Leaving the console open in production. A single manual change is enough to make the environment diverge from Git. The pipeline must at least detect this drift.
  • Starting with production. The chain is first proven between two non-production environments, then extended.

What holds for any gateway

Only the execution layer is specific to webMethods: the playbooks that talk to its administration API. Everything else (Git as the source of truth, a merge request to promote, gates before production, a reread of the actual state, rollback along the same path) transfers as-is to another gateway or integration platform, and even to an estate that mixes several. That is also what makes a future gateway change less risky: the contracts and the chain remain, only the adapter changes.

Where to start

There is no need to migrate everything at once. An approach that works, whatever the platform:

  1. choose a representative API, neither trivial nor critical;
  2. describe its current state in Git, from what already exists;
  3. build the pipeline between two non-production environments, with a reread and a tested rollback;
  4. add the gates (four eyes, ITSM change) before opening production;
  5. extend API by API, measuring time saved and discrepancies detected.

Alongside its consulting work, CAB Ingénierie develops STOA, a sovereign iPaaS and API integration platform.

Let's talk about your project

Are you starting from manual imports, or does your current API deployment chain no longer inspire confidence? Tell us about your context in a few lines: cab-ingenierie.com · contact@cab-ingenierie.com