From bdc193e82c103f34f44657b0a05e7765ed014975 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Fri, 4 Sep 2026 13:09:42 +0000
Subject: [PATCH] docs: fill gaps on GitLab CI setup, multistep non-2xx
 assertions, private locations

---
 .../multistep-checks/troubleshooting.mdx       | 18 ++++++++++++++++++
 integrations/ci-cd/gitlab/overview.mdx         |  9 +++++++++
 platform/private-locations/overview.mdx        |  2 +-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/detect/synthetic-monitoring/multistep-checks/troubleshooting.mdx b/detect/synthetic-monitoring/multistep-checks/troubleshooting.mdx
index 54079978..662bad61 100644
--- a/detect/synthetic-monitoring/multistep-checks/troubleshooting.mdx
+++ b/detect/synthetic-monitoring/multistep-checks/troubleshooting.mdx
@@ -8,6 +8,24 @@ canonical: 'https://www.checklyhq.com/docs/detect/synthetic-monitoring/multistep
 
 Multistep checks are a powerful tool for monitoring complex API workflows. However, they can sometimes be tricky to troubleshoot. Here are some common issues and solutions:
 
+## Expected Non-2xx Responses
+**Issue: A step expects a non-2xx response (like a 401, 403, or 404), the API returns it, but the check still fails**
+
+Playwright's `request` fixture does not throw an error on non-2xx status codes. A 403 response is a completed request. If the check fails, an assertion in your test is failing.
+
+The most common cause is `expect(response).toBeOK()`. This assertion only passes for status codes in the 200-299 range, so it fails on an expected 403.
+
+**Solution**: Assert the exact status code you expect instead of using `toBeOK()`:
+
+```typescript
+await test.step('GET /admin without permissions', async () => {
+  const response = await request.get(`${baseUrl}/admin`, { headers })
+  expect(response.status()).toBe(403)
+})
+```
+
+Check the failing assertion in the check result's error log to confirm which expectation caused the failure.
+
 ## Authentication and Authorization
 **Issue: Authentication failures or token expiration**
 
diff --git a/integrations/ci-cd/gitlab/overview.mdx b/integrations/ci-cd/gitlab/overview.mdx
index 57489653..5e1c3ba2 100644
--- a/integrations/ci-cd/gitlab/overview.mdx
+++ b/integrations/ci-cd/gitlab/overview.mdx
@@ -5,6 +5,15 @@ sidebarTitle: GitLab
 canonical: 'https://www.checklyhq.com/docs/integrations/ci-cd/gitlab/overview/'
 ---
 
+## Prerequisites
+
+Before adding the pipeline, set the required credentials as GitLab CI/CD variables. In your GitLab project, go to **Settings > CI/CD > Variables** and add:
+
+- `CHECKLY_API_KEY`: a Checkly API key, created on the [API keys tab](https://app.checklyhq.com/settings/user/api-keys) in your Checkly user settings. Mark this variable as **Masked** so it does not appear in job logs.
+- `CHECKLY_ACCOUNT_ID`: your Checkly account ID, found on the [Account settings tab](https://app.checklyhq.com/settings/account/general).
+
+The `variables` block in the pipeline example below references these CI/CD variables and exports them to the `checkly test` and `checkly deploy` commands.
+
 ## A Basic GitLab Pipeline Example
 
 Create a new `.gitlab-ci.yml` file in your repo, or add the steps and stages from the example below to your existing file.
diff --git a/platform/private-locations/overview.mdx b/platform/private-locations/overview.mdx
index 2111ac71..bb3e3771 100644
--- a/platform/private-locations/overview.mdx
+++ b/platform/private-locations/overview.mdx
@@ -13,7 +13,7 @@ canonical: 'https://www.checklyhq.com/docs/platform/private-locations/overview/'
 **Owner** or **Admin** permissions are required to create, edit, and delete Private Locations.
 </Note>
 
-A Private Location is a monitoring location that you manage by simply deploying a lightweight Checkly Agent.
+A Private Location is a monitoring location that you manage by simply deploying a lightweight Checkly Agent. The Agent runs as a container on your own infrastructure, whether that is on-premises, in a private cloud, or inside a Kubernetes cluster. Private Locations are Checkly's option for running checks against self-hosted or internal systems that the public internet cannot reach.
 
 Running a check from a Private Location allows you to: