decaporg / decaporg/decap-cms

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

Open
#7,963 0 comments 0 reactions 0 assignees View on GitHub
type: bug
Dominant language
JavaScript
Stars
19.4k
Forks
3.1k
Avg merge
1d 14h
Merged PRs (30d)
9

Description

**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](https://docs.gitlab.com/ee/api/merge_requests.html#merge-a-merge-request)).

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

```yaml
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](https://docs.gitlab.com/ee/api/merge_requests.html#merge-a-merge-request) 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](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14139)

**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](https://docs.gitlab.com/ee/api/branches.html#get-single-repository-branch) 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.

Contributor guide

Open the contributing guide

Research direction

Start with the GitLab backend's editorial-workflow publish and merge-request acceptance path, then read the GitLab Accept MR and Branches API calls described in the issue. Reproduce the failure with a draft entry and verify that publishing uses the current source-branch SHA, merges into main, and removes the entry from Ready to publish.

Written by the indexing model from the issue text.

Assessment

Tech stack
gitlab, javascript
Domain
api, backend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.