Trace a Reviewed Article from GitLab to a Public Page

A publishing job reports success, yet the new article is missing from the public site. Where should you look first: the reviewed text, the merge request, the deployment, or the page itself? A useful answer needs a record at each boundary. Here is a practical design for a Markdown site whose content moves through GitLab.

Freeze what the editor reviewed

Start with one article version: title, body, path, metadata, and any owned images. Give the bytes a SHA-256 digest and record the intended repository base commit. This digest is an engineering design choice, not a GitLab approval feature. It lets your publishing worker reject a changed package after an editor's review. Keep the review record tied to the exact version and digest; if the writer changes the copy, create a new version for review.

Before writing, check the intended path against the repository tree at the chosen base commit. Decide how to handle a collision explicitly. A safe default for a new article is to stop rather than overwrite an existing file. This avoids turning a title or slug typo into a silent content replacement. The tradeoff is that a legitimate revision requires a separate update workflow.

Put the proposed change in a branch and merge request

GitLab lets you create a branch from a branch, tag, or commit SHA. Its commits API can create a commit with a batch of file actions and can start a new branch from a full start_sha (branch documentation, commits API). Use the recorded base commit when creating the article branch, then inspect the resulting commit and file paths. Treat a changed target branch as a reason to recheck collisions and the diff before merge. This base-commit check is a recommended safeguard; merely naming a branch does not freeze the target branch.

Open a merge request from the article branch to the site's target branch. GitLab's merge request flow exposes the source and target branches for review (create a merge request). Review the rendered page if your project has a review environment, but also inspect the actual content diff and required checks. Save the MR URL and the resulting merge commit or target commit. An MR being open, approved, or merged tells you which repository change was reviewed; it does not by itself prove that visitors can read the page.

Match the deployment to the merged content

Configure the site's deployment job to identify the commit it builds. GitLab provides CI_COMMIT_SHA for the revision a pipeline builds, and its deployments view records deployments to environments (predefined variables, deployments). Compare the deployed revision with the commit containing the article. A deployment of an older revision explains why a merged article has not appeared yet.

For stronger evidence, have the build emit a small manifest with the article path and content digest, then retain it with the deployment record. That manifest is your application contract, not a default GitLab deployment field. It helps when a build can succeed while omitting a page because of a route, content filter, or generator error. If builds transform Markdown, choose whether the manifest records source bytes, generated output, or both, and document that choice.

Finally, request the public URL without an editor session. Check that it returns the intended article, canonical URL, and a recognizable content marker. This public-page probe is another recommended check, not an automatic consequence of a successful deployment. A cache can serve an older page after the new deployment, and a private preview can appear correct while the public route fails. Record the observation time and the page identity, then investigate any mismatch at the nearest preceding boundary: review package, commit, merge, deployment, or response. The chain gives an editor a concrete answer to “what went live?” without treating a green job as the final publication receipt.