GitLab backend: editorial workflow publish fails with "SHA must be provided when merging"

[clsined]

Describe the bug

When using the editorial workflow with the GitLab backend, clicking "Publish now" on a draft entry fails with the following error:

API_ERROR: SHA must be provided when merging

The publish action triggers a merge request via the GitLab API, but Decap CMS either does not include the required sha parameter in the merge request acceptance call, or sends a stale SHA that no longer matches the current HEAD of the branch. GitLab's API requires this parameter to prevent race conditions when merging programmatically (see GitLab API docs – Accept MR).

The entry remains stuck in "Ready to publish" status and is never merged into main. The only workaround is to merge the underlying merge request manually from the GitLab interface.

To Reproduce

1. Configure Decap CMS with the GitLab backend and publish_mode: editorial_workflow
2. Create a new entry (blog post or any collection item)
3. Save the entry as a draft — Decap creates a branch and a merge request in GitLab
4. Move the entry to "Ready to publish" status
5. Click "Publish now"
6. Observe the error: API_ERROR: SHA must be provided when merging

The error is consistent and reproducible on every publish attempt. It does not occur when merging the same MR manually from GitLab.

Expected behavior

Clicking "Publish now" should successfully merge the draft branch into main via the GitLab API, triggering a rebuild of the static site. The entry should disappear from the workflow board and be visible on the published site.

Screenshots

Applicable Versions:

• Decap CMS version: 3.15.1 (loaded via https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js)
• Git provider: GitLab (gitlab.com)
• OS: macOS
• Browser version: Chrome 126, Firefox 127 (reproduced on both)
• Node.JS version: N/A (CDN install)

CMS configuration

backend:
  name: gitlab
  repo: username/repo-name
  branch: main
  auth_type: pkce
  app_id: YOUR_APP_ID

publish_mode: editorial_workflow

media_folder: public/images/uploads
public_folder: /images/uploads

locale: fr

collections:
  - name: blog
    label: Articles
    folder: src/content/blog
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - { label: Titre, name: title, widget: string }
      - { label: Date, name: date, widget: datetime }
      - { label: Contenu, name: body, widget: markdown }

Additional context

• The bug is specific to the GitLab backend. The GitHub backend does not exhibit this behavior.
• The GitLab API's Accept MR endpoint requires a sha parameter matching the current HEAD of the source branch when merging via API. If this parameter is missing or stale, GitLab returns a 405 error with the message SHA must be provided when merging.
• A partial workaround exists by adding squash_merges: true to the backend config, which appears to force Decap to re-fetch the branch HEAD before merging. However, this is not a reliable fix for all users and changes the commit history behavior.
• This issue has been observed consistently across multiple Astro.js projects using GitLab Pages as the deployment target.
• Related GitLab upstream issue: SHA parameter in accept merge request API

Suggested fix

Before calling the GitLab merge API endpoint, Decap CMS should fetch the current HEAD SHA of the source branch using the GitLab Branches API and include it as the sha parameter in the merge request acceptance call. This ensures the SHA is always up to date at the moment of the merge, regardless of any intermediate commits.