“We are going to put our APIs in Git.” The sentence comes up in almost every industrialisation effort we support, whatever the gateway: a vendor product, an open-source solution or a managed service from a cloud provider. The intention is sound. But between the intention and a repository that genuinely serves as a source of truth, there is a series of choices one later regrets not having made at the start.

This article gathers those choices. It does not depend on any product: the same questions arise on every gateway and integration platform we have come across.

The starting trap: versioning the console export

The first attempt often looks like this: the configuration is exported from the administration console, pushed into Git, and the job is considered done. Three problems appear quickly:

  • the export is not meant to be reviewed: binary formats or JSON several thousand lines long, generated fields, timestamps that change with every export;
  • it contains identifiers specific to an environment: a staging export cannot be replayed as-is in production;
  • it sometimes carries sensitive values: backend passwords, keys, certificates.

A repository where every diff is three hundred lines of noise is not reviewed. And a repository that is not reviewed is not a source of truth; it is a backup.

What belongs in the repository

The rule we apply: we version the intent, not the technical state. In practice, an API repository contains four families of files.

1. The contract

The interface specification: OpenAPI for REST, WSDL for SOAP, AsyncAPI for event-driven flows. This is the most important document, because it is the one consumers see. It can be reviewed like code, validated automatically (lint, style rules) and compared from one version to the next to detect breaks.

2. The policy description

Required authentication, traffic limits, routing, transformations: described in a readable format, as independent as possible of the gateway’s internal format. The aim is that a reviewer can understand what is changing by reading the diff, without knowing the console.

It is the deployment layer that translates this description into the gateway’s own format. This separation has an unexpected benefit: the day the gateway changes, the intent is already written down.

3. Per-environment values

Backend URLs, aliases, quotas, certificate names: one file per environment, in a simple format. These files contain only what actually varies from one environment to another. If an environment file looks like a copy of the contract, the separation has been done poorly.

4. The target version per environment

A file that says “in staging, version 2.3; in production, version 2.2”. Promoting an API means changing this file through a merge request. The Git history then answers directly the question “what was running in production on that day?”.

What should never go there

  • Secrets. No password, no private key, no token, even “temporarily” encrypted. We version a reference (the name of the secret in the vault), and the value is read at deployment time. A secret pushed once into the Git history must be treated as exposed and rotated: deleting it in a later commit does not erase it from the history.
  • Technical identifiers generated by the gateway. They change from one environment to another and from one reinstallation to another. The pipeline resolves them at deployment time.
  • Operational data. Statistics, logs, transient activation states: this is not configuration.
  • Artefacts produced by the pipeline. Export archives, packages, generated files: they can be rebuilt from the repository and stored, if needed, in an artefact repository.

One repository per API, or one repository for everything?

There is no universal right answer. What we observe:

  • one repository per API or per domain gives fine-grained permissions (each team manages its APIs), readable histories and fast pipelines;
  • a central repository makes cross-cutting changes easier (a policy shared by all APIs) and the overall view simpler, but permissions and reviews become heavier;
  • a frequent compromise: one repository per domain for the APIs, and a foundation repository for shared policies and templates, consumed by the others.

The decisive criterion is organisational: who reviews, who approves, who is woken up in an incident. The structure of the repository should follow the structure of responsibilities.

Branches, tags and promotion

We recommend a simple model:

  • a protected main branch, which can only be updated through a reviewed merge request;
  • a tag for each published version of the contract;
  • promotion between environments by changing the target-version file, not by having one branch per environment.

The “one branch per environment” model looks intuitive, but it quickly produces diverging branches and risky merges. A single history, tagged versions, and a file that says which version goes where: that is easier to audit.

Detecting drift

Versioning in Git is pointless if someone can still change production by hand without anyone noticing. Two mechanisms complete the setup:

  • a reread of the actual state after every deployment, compared with the expected state;
  • a periodic drift check, which compares the environment with the repository and flags any discrepancy, even without a deployment.

The frequency of the check and the time taken to handle discrepancies are defined with the teams, depending on each context.

Where to start

  1. Choose a representative API and write its contract properly, if it does not already exist in a usable form.
  2. Describe its policies and environment values in separate files.
  3. Write the deployment layer for a single gateway and two non-production environments.
  4. Add the post-deployment reread, then the drift check.
  5. Only then, generalise.

The hardest part is not technical: it is getting everyone to stop changing the configuration outside the repository. That is why the structure must be simple enough for the Git path to also be the easiest path.

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

Let's talk about your project

Do you want to make Git the source of truth for your APIs, or has your current repository stopped playing that role? Tell us about your context in a few lines: cab-ingenierie.com · contact@cab-ingenierie.com