Commit fb9fec00 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis Committed by Rémy Coutable

Refine docs trigger script and use a really long branch name to test it

parent 706426d5
......@@ -174,7 +174,8 @@ build-package:
# Review docs base
.review-docs: &review-docs
image: ruby:2.4-alpine
before_script: []
- gem install gitlab --no-doc
services: []
SETUP_DB: "false"
......@@ -193,10 +194,9 @@ review-docs-deploy:
name: review-docs/$CI_COMMIT_REF_NAME
# Discussion:
on_stop: review-docs-cleanup
- gem install gitlab --no-doc
- scripts/trigger-build-docs deploy
# Cleanup remote environment of gitlab-docs
......@@ -207,7 +207,6 @@ review-docs-cleanup:
name: review-docs/$CI_COMMIT_REF_NAME
action: stop
- gem install gitlab --no-doc
- scripts/trigger-build-docs cleanup
# Retrieve knapsack and rspec_flaky reports
......@@ -106,21 +106,84 @@ CE and EE.
## Previewing the changes live
If you want to preview your changes live, you can use the manual `build-docs`
job in your merge request.
If you want to preview the doc changes of your merge request live, you can use
the manual `review-docs-deploy` job in your merge request.
TIP: **Tip:**
If your branch contains only documentation changes, you can use
[special branch names](#testing) to avoid long running pipelines.
![Manual trigger a docs build](img/manual_build_docs.png)
This job will:
1. Create a new branch in the [gitlab-docs](
project named after the scheme: `<CE/EE-branch-slug>-built-from-ce-ee`
1. Trigger a pipeline and build the docs site with your changes
Look for the docs URL at the output of the `build-docs` job.
project named after the scheme: `preview-<branch-slug>`
1. Trigger a cross project pipeline and build the docs site with your changes
After a few minutes, the Review App will be deployed and you will be able to
preview the changes. The docs URL can be found in two places:
- In the merge request widget
- In the output of the `review-docs-deploy` job, which also includes the
triggered pipeline so that you can investigate whether something went wrong
In case the Review App URL returns 404, follow these steps to debug:
1. **Did you follow the URL from the merge request widget?** If yes, then check if
the link is the same as the one in the job output. It can happen that if the
branch name slug is longer than 35 characters, it is automatically
truncated. That means that the merge request widget will not show the proper
URL due to a limitation of how `environment: url` works, but you can find the
real URL from the output of the `review-docs-deploy` job.
1. **Did you follow the URL from the job output?** If yes, then it means that
either the site is not yet deployed or something went wrong with the remote
pipeline. Give it a few minutes and it should appear online, otherwise you
can check the status of the remote pipeline from the link in the job output.
If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
TIP: **Tip:**
Someone that has no merge rights to the CE/EE projects (think of forks from
contributors) will not be able to run the manual job. In that case, you can
ask someone from the GitLab team who has the permissions to do that for you.
NOTE: **Note:**
Make sure that you always delete the branch of the merge request you were
working on. If you don't, the remote docs branch won't be removed either,
and the server where the Review Apps are hosted will eventually be out of
disk space.
### Behind the scenes
If you want to know the hot details, here's what's really happening:
1. You manually run the `review-docs-deploy` job in a CE/EE merge request.
1. The job runs the [`scirpts/trigger-build-docs`](
script with the `deploy` flag, which in turn:
1. Takes your branch name and applies the following:
- The slug of the branch name is used to avoid special characters since
ultimately this will be used by NGINX.
- The `preview-` prefix is added to avoid conflicts if there's a remote branch
with the same name that you created in the merge request.
- The final branch name is truncated to 42 characters to avoid filesystem
limitations with long branch names (> 63 chars).
1. The remote branch is then created if it doesn't exist (meaning you can
re-run the manual job as many times as you want and this step will be skipped).
1. A new cross-project pipeline is triggered in the docs project.
1. The preview URL is shown both at the job output and in the merge request
widget. You also get the link to the remote pipeline.
1. In the docs project, the pipeline is created and it
[skips the test jobs](
to lower the build time.
1. Once the docs site is built, the HTML files are uploaded as artifacts.
1. A specific Runner tied only to the docs project, runs the Review App job
that downloads the artifacts and uses `rsync` to transfer the files over
to a location where NGINX serves them.
The following GitLab features are used among others:
- [Manual actions](../ci/yaml/
- [Multi project pipelines](
- [Review Apps](../ci/review_apps/
- [Artifacts](../ci/yaml/
- [Specific Runner](../ci/runners/
......@@ -2,13 +2,6 @@
require 'gitlab'
# Give the remote branch a different name than the current one
# in order to avoid conflicts
@docs_branch = "#{ENV["CI_COMMIT_REF_SLUG"]}-built-from-ce-ee"
GITLAB_DOCS_REPO = 'gitlab-com/gitlab-docs'.freeze
# Configure credentials to be used with gitlab gem
......@@ -17,6 +10,26 @@ Gitlab.configure do |config|
config.private_token = ENV["DOCS_API_TOKEN"] # GitLab Docs bot access token which has only Developer access to gitlab-docs
# The remote docs project
GITLAB_DOCS_REPO = 'gitlab-com/gitlab-docs'.freeze
# Truncate the remote docs branch name if it's more than 63 characters
# otherwise we hit the filesystem limit and the directory name where
# NGINX serves the site won't match the branch name.
def docs_branch
# The maximum string length a file can have on a filesystem (ext4)
# is 63 characters. Let's use something smaller to be 100% sure.
max = 42
# Prefix the remote branch with 'preview-' in order to avoid
# name conflicts in the rare case the branch name already
# exists in the docs repo and truncate to max length.
# Dummy way to find out in which repo we are, CE or EE
......@@ -28,18 +41,18 @@ end
# Create a remote branch in gitlab-docs
def create_remote_branch
Gitlab.create_branch(GITLAB_DOCS_REPO, @docs_branch, 'master')
puts "Remote branch '#{@docs_branch}' created"
Gitlab.create_branch(GITLAB_DOCS_REPO, docs_branch, 'master')
puts "Remote branch '#{docs_branch}' created"
rescue Gitlab::Error::BadRequest
puts "Remote branch '#{@docs_branch}' already exists"
puts "Remote branch '#{docs_branch}' already exists"
# Remove a remote branch in gitlab-docs
def remove_remote_branch
Gitlab.delete_branch(GITLAB_DOCS_REPO, @docs_branch)
puts "Remote branch '#{@docs_branch}' deleted"
Gitlab.delete_branch(GITLAB_DOCS_REPO, docs_branch)
puts "Remote branch '#{docs_branch}' deleted"
......@@ -50,11 +63,11 @@ def trigger_pipeline
param_name = ee? ? 'BRANCH_EE' : 'BRANCH_CE'
# The review app URL
app_url = "http://#{@docs_branch}.#{ENV["DOCS_REVIEW_APPS_DOMAIN"]}/#{ee? ? 'ee' : 'ce'}"
app_url = "http://#{docs_branch}.#{ENV["DOCS_REVIEW_APPS_DOMAIN"]}/#{ee? ? 'ee' : 'ce'}"
# Create the pipeline
puts "=> Triggering a pipeline..."
pipeline = Gitlab.run_trigger(GITLAB_DOCS_REPO, ENV["DOCS_TRIGGER_TOKEN"], @docs_branch, { param_name => ENV["CI_COMMIT_REF_NAME"] })
pipeline = Gitlab.run_trigger(GITLAB_DOCS_REPO, ENV["CI_JOB_TOKEN"], docs_branch, { param_name => ENV["CI_COMMIT_REF_NAME"] })
puts "=> Pipeline created:"
puts ""
......@@ -77,4 +90,8 @@ when 'deploy'
when 'cleanup'
puts "Please provide a valid option:
deploy - Creates the remote branch and triggers a pipeline
cleanup - Deletes the remote branch and stops the Review App"
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment