Fix race condition when previewing docs

Cancel the pipeline that gets created the first time the remote
branch is created in order not to overwrite the one we trigger
afterwards.

Closes https://gitlab.com/gitlab-com/gitlab-docs/issues/154

scripts/trigger-build-docs

@@ -7,7 +7,7 @@ require 'gitlab'
 #
 Gitlab.configure do |config|
   config.endpoint       = 'https://gitlab.com/api/v4'
-  config.private_token  = ENV["DOCS_API_TOKEN"]  # GitLab Docs bot access token which has only Developer access to gitlab-docs
+  config.private_token  = ENV["DOCS_API_TOKEN"] # GitLab Docs bot access token with Developer access to gitlab-docs
 end
 
 #
@@ -31,13 +31,24 @@ def docs_branch
 end
 
 #
-# Create a remote branch in gitlab-docs
+# Create a remote branch in gitlab-docs and immediately cancel the pipeline
+# to avoid race conditions, since a triggered pipeline will also run right
+# after the branch creation. This only happens the very first time a branch
+# is created and will be skipped in subsequent runs. Read more in
+# https://gitlab.com/gitlab-com/gitlab-docs/issues/154.
 #
 def create_remote_branch
   Gitlab.create_branch(GITLAB_DOCS_REPO, docs_branch, 'master')
-  puts "Remote branch '#{docs_branch}' created"
+  puts "=> Remote branch '#{docs_branch}' created"
+
+  # Get the latest pipeline ID which is also the first
+  pipeline_id = Gitlab.pipelines(GITLAB_DOCS_REPO, { ref: docs_branch }).last.id
+
+  # Cancel the pipeline
+  Gitlab.cancel_pipeline(GITLAB_DOCS_REPO, pipeline_id)
+  puts "=> Canceled uneeded pipeline #{pipeline_id} for '#{docs_branch}'"
 rescue Gitlab::Error::BadRequest
-  puts "Remote branch '#{docs_branch}' already exists"
+  puts "=> Remote branch '#{docs_branch}' already exists"
 end
 
 #
@@ -45,7 +56,7 @@ end
 #
 def remove_remote_branch
   Gitlab.delete_branch(GITLAB_DOCS_REPO, docs_branch)
-  puts "Remote branch '#{docs_branch}' deleted"
+  puts "=> Remote branch '#{docs_branch}' deleted"
 end
 
 #
@@ -78,18 +89,22 @@ def trigger_pipeline
   # The review app URL
   app_url = "http://#{docs_branch}.#{ENV["DOCS_REVIEW_APPS_DOMAIN"]}/#{slug}"
 
-  # Create the pipeline
-  puts "=> Triggering a pipeline..."
+  # Create the cross project pipeline using CI_JOB_TOKEN
   pipeline = Gitlab.run_trigger(GITLAB_DOCS_REPO, ENV["CI_JOB_TOKEN"], docs_branch, { param_name => ENV["CI_COMMIT_REF_NAME"] })
 
-  puts "=> Pipeline created:"
+  puts "=> Follow the status of the triggered pipeline:"
   puts ""
   puts "https://gitlab.com/gitlab-com/gitlab-docs/pipelines/#{pipeline.id}"
   puts ""
-  puts "=> Preview your changes live at:"
+  puts "=> In a few minutes, you will be able to preview your changes under the following URL:"
   puts ""
   puts app_url
   puts ""
+  puts "=> For more information, read the documentation"
+  puts "=> https://docs.gitlab.com/ee/development/writing_documentation.html#previewing-the-changes-live"
+  puts ""
+  puts "=> If something doesn't work, drop a line in the #docs chat channel."
+  puts ""
 end
 
 #