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.

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.7

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.7
File Size Uploaded Provenance Actions
lcdp_back_merge-1.0.7.tar.gz 26.7 kB Without provenance Details for lcdp_back_merge-1.0.7.tar.gz

Built distribution (wheel)

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

Total release size: 57.0 kB

Release files / lcdp_back_merge-1.0.7.tar.gz

Download URL lcdp_back_merge-1.0.7.tar.gz
Size 26.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3a7b8c57945a970a0dedb6b6f0a47b1b324a07f84aab640040c16b2b89a6d76e
BLAKE2b-256 checksum
How to use checksums
dfc6d2b458a1871119553812f9ef3094f0c8f6761ce36d98ee6897ce24503ae3
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.7-py3-none-any.whl

Download URL lcdp_back_merge-1.0.7-py3-none-any.whl
Size 30.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c759b0d8a546fdd36b6e73bdeebc339bf63dae7050e1731eb37577b046d37b5d
BLAKE2b-256 checksum
How to use checksums
f32c59051e55a0515bd33e8132f1396eb2a0cbbf56cb8e3055952461f96f5f2f
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.7

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