Skip to main content

lcdp-back-merge

Bot de back-merge automatique multi-plateforme (Bitbucket Cloud / GitHub) avec résolution IA des conflits.

Quoi ça fait

Pour chaque branche divergente de la branche source courante :

  1. Crée une branche auto-merge/<source>-into-<target>
  2. Tente le merge ; si conflit, demande à Claude une proposition de résolution par fichier
  3. Ouvre une PR avec une description riche (statut, fichiers en conflit, suggestions IA)
  4. Auto-merge si pas de conflit OU si l'IA a résolu tous les fichiers avec confiance high
  5. Notifie Slack sinon (review requise)

Les commits créés par le bot sur la branche auto-merge/* portent [skip ci] pour éviter une CI redondante sur cette branche éphémère :

  • GitHub Actions : saute les workflows sur push et pull_request.
  • Bitbucket : saute les builds de branche uniquement — pas les pipelines pull-requests: (BCLOUD-17676, limite Bitbucket sans contournement).

Sans effet sur la branche de destination : le bot merge en vrai merge commit (merge_commit / merge), dont le message ne contient pas le tag. La CI de develop tourne donc normalement après le merge.

Auto-merge et mergeabilité asynchrone (GitHub). GitHub calcule mergeable après coup : une PR qui vient d'être créée renvoie null, et un PUT /merge immédiat est rejeté en 405 Base branch was modified. Le bot attend donc que mergeable soit tranché avant de merger, et retente un 405/409 sur le merge lui-même. Un mergeable: false est un verdict — conflit réel, pas de retry. Sans cette attente, l'auto-merge perdait la course et laissait la PR ouverte avec un simple WARN : sur lcdp-inventorist-app, le back-merge de v2.2.0 est resté ouvert sept semaines et a fait échouer la release v2.2.1 sur le conflit correspondant. Depuis LDS-6140, un auto-merge raté fait aussi échouer le step (voir ci-dessous) : le WARN n'est plus le seul signal.

Pins lcdp-api : le prompt décide, le code encadre

Un conflit sur un pin de version (conf/version.conf, package.json, pom.xml, build.sbt, pyproject.toml) n'est pas un conflit textuel : la bonne valeur est l'artefact lcdp-api qui contient les deux contrats, et cette information vit dans lcdp-api, pas dans le dépôt mergé. Sur la PR 2793 du monolithe, l'IA avait trouvé la bonne version mais refusait de l'appliquer par prudence générique (LDS-6236). Le system prompt porte donc une règle métier, appliquée quand la cible est develop :

Côté A Côté B Résolution
release X.Y.Z ou snapshot develop X.Y.Z-SNAPSHOT / X.Y.Z-develop.N idem la plus haute ; à numéro égal, la release
snapshot de branche X.Y.Z-<branche>-SNAPSHOT / X.Y.Z-<branche>.N release ou snapshot develop de numéro ≥ X.Y.Z le côté release / develop (la branche est supposée mergée dans lcdp-api)
snapshot de branche release ou snapshot develop de numéro < X.Y.Z pas de résolution : la bonne version n'est sur aucun des deux côtés
snapshot de branche snapshot de branche pas de résolution
python X.Y.Z.postN+git.<sha> — la chaîne ne distingue pas develop d'une branche : règle inapplicable

Deux bornes déterministes dans ai_resolver.py, hors de portée du modèle :

  • chaque ligne de la résolution d'un manifeste doit exister dans l'un des deux côtés du conflit (une version qui n'apparaît nulle part est rejetée, le fichier reste en conflit) ;
  • la confiance d'un pick de pin est plafonnée à medium : la résolution est commitée sur auto-merge/* (acceptable en un clic via use source dans la UI Bitbucket) mais n'auto-merge jamais. Le pire cas d'un mauvais pick est un pipeline develop rouge à la compile, visible en minutes, jamais un déploiement.

Code de sortie : un vert est une preuve

Le step sort en 1 dès qu'un back-merge nécessaire n'a pas abouti, et le résumé Done. liste les branches en échec avec la cause (stderr de git push, erreur API de la plateforme). Sans ça, le step restait vert quand le push ou la création de PR était refusée : sur lcdp-front-mono, deux releases sont restées absentes de develop pendant deux semaines sans que personne ne le voie (LDS-6140).

Situation Step Slack
Merge propre auto-mergé vert —
PR laissée ouverte pour conflits non résolus vert « review requise » (bouton Voir la PR)
Push de auto-merge/* refusé rouge « NON effectué » (bouton Voir la pipeline)
Création de PR refusée rouge « NON effectué »
Auto-merge d'un merge propre raté rouge « review requise » (la PR reste ouverte)
Erreur git inattendue sur une branche rouge « NON effectué »
Suppression d'une auto-merge/* orpheline refusée WARN seulement —

Un échec sur une branche n'arrête pas le run : les autres branches du branch_map sont traitées, puis le step échoue. Le refus de suppression d'une orpheline n'est pas compté en soi : si elle bloque vraiment, c'est le push qui échoue juste après, avec cette raison dans le log. Un rouge sur ce step ne concerne jamais le déploiement de la source : seule la propagation vers la cible a échoué.

Tests

poetry install --with dev
poetry run pytest tests

Configuration

Variables d'environnement requises

Variable Plateforme Description
BB_AUTH_STRING Bitbucket client_id:client_secret OAuth pour l'API Bitbucket
GITHUB_APP_ID GitHub App ID du GitHub App (auth App uniquement, pas de PAT)
GITHUB_APP_PRIVATE_KEY GitHub Clé privée PEM du GitHub App. Permissions requises : contents:write + pull-requests:write

La plateforme est détectée automatiquement via les variables CI standard (BITBUCKET_BRANCH, GITHUB_ACTIONS).

GitHub : l'auth se fait exclusivement via GitHub App (le script génère lui-même un installation token court). L'App doit être installée sur le repo cible.

Variables d'environnement optionnelles

Variable Défaut Description
ANTHROPIC_API_KEY — Active la résolution IA des conflits
ANTHROPIC_MODEL claude-sonnet-4-6 Modèle Claude utilisé pour la résolution
SLACK_WEBHOOK_URL — Active les notifications Slack
AUTO_MERGE_TARGET_PATTERNS (toutes) Globs séparés par virgule : develop,release/*
AUTO_MERGE_BRANCH_MAP — Mapping source→patterns : master:develop;develop:feature/*
AUTO_MERGE_DEFAULT_REVIEWERS — Reviewers fallback en CSV (UUIDs Bitbucket ou logins GitHub)
AUTO_MERGE_PR_RUN_LIMIT -1 (illimité) Nombre max de PR créées par run
AUTO_MERGE_SOURCE_BRANCH branche CI Branche à back-merger, à la place de celle qui a déclenché la CI

GitHub : ne pas surcharger GITHUB_* pour changer la source. Actions ignore en silence un env: GITHUB_REF_NAME: main posé sur un step. Un workflow lancé depuis release/vX qui doit back-merger main pose AUTO_MERGE_SOURCE_BRANCH: main. Le log de démarrage affiche la source effective et la variable lue : Source branch: main (from AUTO_MERGE_SOURCE_BRANCH).

Utilisation en pipeline

Bitbucket Pipelines

branches:
  "{master}":
    - step:
        name: Back merge
        # image uv officielle (debian bookworm) → uv + git déjà présents
        image: ghcr.io/astral-sh/uv:python3.11-bookworm
        clone:
          depth: full          # toutes les branches divergentes
        script:
          - export AUTO_MERGE_TARGET_PATTERNS="develop"
          - uvx lcdp-back-merge
        # Variables (repository/deployment) : BB_AUTH_STRING, ANTHROPIC_API_KEY, SLACK_WEBHOOK_URL

GitHub Actions

- uses: actions/checkout@v4
  with:
    fetch-depth: 0          # toutes les branches divergentes
    persist-credentials: false   # le script gère l'auth git via le token App
- uses: astral-sh/setup-uv@v5
- name: Back-merge
  run: uvx lcdp-back-merge
  env:
    # Noms des secrets GitHub explicites (à gauche = ce que lit le script,
    # à droite = le secret/variable côté repo, nommé sans ambiguïté).
    GITHUB_APP_ID: ${{ vars.LCDP_BACKMERGE_APP_ID }}
    GITHUB_APP_PRIVATE_KEY: ${{ secrets.LCDP_BACKMERGE_APP_PRIVATE_KEY }}
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Architecture

lcdp_back_merge/
├── cli.py              # argparse, entry point
├── runner.py           # boucle principale, orchestration
├── ai_resolver.py      # résolution de conflits via Claude
├── slack.py            # notifications Slack
├── git_utils.py        # wrappers subprocess git
└── platforms/
    ├── base.py         # abstract Platform
    ├── bitbucket.py    # adaptateur Bitbucket Cloud
    └── github.py       # adaptateur GitHub

Ajouter une plateforme = ajouter une sous-classe de Platform dans platforms/, l'enregistrer dans platforms.__init__.detect_platform().

Metadata

Release files for lcdp-back-merge 1.0.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lcdp-back-merge 1.0.10
File Size Uploaded Provenance Actions
lcdp_back_merge-1.0.10.tar.gz 30.1 kB Without provenance Details for lcdp_back_merge-1.0.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lcdp-back-merge 1.0.10
File Interpreter ABI Platform Actions
lcdp_back_merge-1.0.10-py3-none-any.whl Python 3 none any Details for lcdp_back_merge-1.0.10-py3-none-any.whl

Total release size: 63.3 kB

Release files / lcdp_back_merge-1.0.10.tar.gz

Download URL lcdp_back_merge-1.0.10.tar.gz
Size 30.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e63cf41974dadae3c6c72f5432fbc9f0c60b19b68dac1d0d24cf1ef4ef4481b0
BLAKE2b-256 checksum
How to use checksums
2607335995d5199733f786ed3ab8b738bb35a16dc91fa1fecb87ac32110fe561
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.12.3 Linux/6.18.35

Release files / lcdp_back_merge-1.0.10-py3-none-any.whl

Download URL lcdp_back_merge-1.0.10-py3-none-any.whl
Size 33.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c85bd0cb791fa1230febaabfd2c2467717766ab1b7107fe1e4b867128090eb9d
BLAKE2b-256 checksum
How to use checksums
c59bb2bc022d2d850b477c7567dd3c4262e8a641cefcdd75fc673e11ccce1f24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.12.3 Linux/6.18.35

Security for lcdp-back-merge 1.0.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page