diff --git a/.changeset/lazy-zoos-move.md b/.changeset/lazy-zoos-move.md
index 1e94ec798f..4bd78cee1d 100644
--- a/.changeset/lazy-zoos-move.md
+++ b/.changeset/lazy-zoos-move.md
@@ -3,3 +3,65 @@
 ---
 
 Add a new provider `GitlabDiscoveryEntityProvider` as replacement for `GitlabDiscoveryProcessor`
+
+In order to migrate from the `GitlabDiscoveryProcessor` you need to apply
+the following changes:
+
+**Before:**
+
+```yaml
+# app-config.yaml
+
+catalog:
+  locations:
+    - type: gitlab-discovery
+      target: https://company.gitlab.com/prefix/*/catalog-info.yaml
+```
+
+```ts
+/* packages/backend/src/plugins/catalog.ts */
+
+import { GitlabDiscoveryProcessor } from '@backstage/plugin-catalog-backend-module-gitlab';
+
+const builder = await CatalogBuilder.create(env);
+/** ... other processors ... */
+builder.addProcessor(
+  GitLabDiscoveryProcessor.fromConfig(env.config, { logger: env.logger }),
+);
+```
+
+**After:**
+
+```yaml
+# app-config.yaml
+
+catalog:
+  providers:
+    gitlab:
+      yourProviderId: # identifies your dataset / provider independent of config changes
+        host: gitlab-host # Identifies one of the hosts set up in the integrations
+        branch: main # Optional. Uses `master` as default
+        group: example-group # Group and subgroup (if needed) to look for repositories
+        entityFilename: catalog-info.yaml # Optional. Defaults to `catalog-info.yaml`
+        rules: # Optional. Uses the default rules if not present
+          - repository: example-repo
+            allow: [Component, System, Location, Template]
+```
+
+```ts
+/* packages/backend/src/plugins/catalog.ts */
+
+import { GitlabDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
+
+const builder = await CatalogBuilder.create(env);
+/** ... other processors and/or providers ... */
+builder.addEntityProvider(
+  ...GitlabDiscoveryEntityProvider.fromConfig(env.config, {
+    logger: env.logger,
+    schedule: env.scheduler.createScheduledTaskRunner({
+      frequency: { minutes: 30 },
+      timeout: { minutes: 3 },
+    }),
+  }),
+);
+```
diff --git a/docs/integrations/gitlab/discovery.md b/docs/integrations/gitlab/discovery.md
index 986c2aec15..6383e70e64 100644
--- a/docs/integrations/gitlab/discovery.md
+++ b/docs/integrations/gitlab/discovery.md
@@ -24,7 +24,7 @@ catalog:
         branch: main # Optional. Uses `master` as default
         group: example-group # Group and subgroup (if needed) to look for repositories
         entityFilename: catalog-info.yaml # Optional. Defaults to `catalog-info.yaml`
-        rules:
+        rules: # Optional. Uses the default rules if not present
           - repository: example-repo
             allow: [Component, System, Location, Template]
 ```
@@ -42,7 +42,7 @@ Once you've done that, you'll also need to add the segment below to `packages/ba
 ```ts
 /* packages/backend/src/plugins/catalog.ts */
 
-import { GitlabDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-aws';
+import { GitlabDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
 
 const builder = await CatalogBuilder.create(env);
 /** ... other processors and/or providers ... */