docs(projects): document 404 gotcha with unactivated integrations

1 files changed, 17 insertions, 6 deletions

diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index fcf55e6..7569d74 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -628,7 +628,23 @@ Reference
 Examples
 ---------
 
-Get a service::
+.. danger::
+
+    Since GitLab 13.12, ``get()`` calls to project services return a
+    ``404 Not Found`` response until they have been activated the first time.
+
+    To avoid this, we recommend using `lazy=True` to prevent making
+    the initial call when activating new services unless they have
+    previously already been activated.
+
+Configure and enable a service for the first time::
+
+    service = project.services.get('asana', lazy=True)
+
+    service.api_key = 'randomkey'
+    service.save()
+
+Get an existing service::
 
     service = project.services.get('asana')
     # display its status (enabled/disabled)
@@ -642,11 +658,6 @@ List the code names of available services (doesn't return objects)::
 
     services = project.services.available()
 
-Configure and enable a service::
-
-    service.api_key = 'randomkey'
-    service.save()
-
 Disable a service::
 
     service.delete()