diff options
-rw-r--r-- | .gitlab/ci/build-and-deploy.gitlab-ci.yml (renamed from .gitlab/ci/deploy.gitlab-ci.yml) | 0 | ||||
-rw-r--r-- | .gitlab/issue_templates/release.md | 2 | ||||
-rw-r--r-- | Rakefile | 22 | ||||
-rw-r--r-- | content/_data/navigation.yaml | 17 | ||||
-rw-r--r-- | doc/architecture.md | 26 | ||||
-rw-r--r-- | lib/task_helpers.rb | 152 | ||||
-rw-r--r-- | spec/lib/task_helpers_spec.rb | 19 |
7 files changed, 147 insertions, 91 deletions
diff --git a/.gitlab/ci/deploy.gitlab-ci.yml b/.gitlab/ci/build-and-deploy.gitlab-ci.yml index e1ba016e..e1ba016e 100644 --- a/.gitlab/ci/deploy.gitlab-ci.yml +++ b/.gitlab/ci/build-and-deploy.gitlab-ci.yml diff --git a/.gitlab/issue_templates/release.md b/.gitlab/issue_templates/release.md index 8702a32d..17285a1e 100644 --- a/.gitlab/issue_templates/release.md +++ b/.gitlab/issue_templates/release.md @@ -55,7 +55,7 @@ After release post is live on the 22nd, or the next Monday morning if the releas After the 22nd of each month: 1. [ ] Create a release issue for the - [next TW](https://about.gitlab.com/handbook/marketing/blog/release-posts/managers/) + [next TW](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks) and assign it to them. 1. [ ] **Major releases only.** Update [OutdatedVersions.yml](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OutdatedVersions.yml) @@ -8,6 +8,8 @@ COLOR_CODE_RESET = "\e[0m" COLOR_CODE_RED = "\e[31m" COLOR_CODE_GREEN = "\e[32m" +task_helpers = TaskHelpers.new + task default: [:clone_repositories, :generate_feature_flags] task :setup_git do @@ -19,8 +21,8 @@ end desc 'Clone Git repositories of documentation projects, keeping only the most recent commit' task :clone_repositories do - products.each_value do |product| - branch = retrieve_branch(product['slug']) + task_helpers.products.each_value do |product| + branch = task_helpers.retrieve_branch(product['slug']) # Limit the pipeline to pull only the repo where the MR is, not all 4, to save time/space. # First we check if the branch on the docs repo is other than the default branch and @@ -87,12 +89,12 @@ namespace :release do # Check if local branch exists abort("\n#{COLOR_CODE_RED}ERROR: Rake aborted! The branch already exists. Delete it with `git branch -D #{version}` and rerun the task.#{COLOR_CODE_RESET}") \ - if local_branch_exist?(version) + if task_helpers.local_branch_exist?(version) # Stash modified and untracked files so we have "clean" environment # without accidentally deleting data puts "\n#{COLOR_CODE_GREEN}INFO: Stashing changes..#{COLOR_CODE_RESET}" - `git stash -u` if git_workdir_dirty? + `git stash -u` if task_helpers.git_workdir_dirty? # Sync with upstream default branch `git checkout #{ENV['CI_DEFAULT_BRANCH']}` @@ -111,7 +113,7 @@ namespace :release do content = File.read('dockerfiles/single.Dockerfile') content.gsub!('X.Y', version) content.gsub!('X-Y', version.tr('.', '-')) - content.gsub!('W-Z', chart_version(version).tr('.', '-')) + content.gsub!('W-Z', task_helpers.chart_version(version).tr('.', '-')) File.open(dockerfile, 'w') do |post| post.puts content @@ -123,7 +125,7 @@ namespace :release do ci_yaml_content.gsub!("BRANCH_EE: 'master'", "BRANCH_EE: '#{version.tr('.', '-')}-stable-ee'") ci_yaml_content.gsub!("BRANCH_OMNIBUS: 'master'", "BRANCH_OMNIBUS: '#{version.tr('.', '-')}-stable'") ci_yaml_content.gsub!("BRANCH_RUNNER: 'main'", "BRANCH_RUNNER: '#{version.tr('.', '-')}-stable'") - ci_yaml_content.gsub!("BRANCH_CHARTS: 'master'", "BRANCH_CHARTS: '#{chart_version(version).tr('.', '-')}-stable'") + ci_yaml_content.gsub!("BRANCH_CHARTS: 'master'", "BRANCH_CHARTS: '#{task_helpers.chart_version(version).tr('.', '-')}-stable'") File.open(ci_yaml, 'w') do |post| post.puts ci_yaml_content @@ -181,12 +183,12 @@ namespace :docs do abort("\n#{COLOR_CODE_RED}ERROR: jq not found. Install jq and run task again.#{COLOR_CODE_RESET}") if `which jq`.empty? puts "\n#{COLOR_CODE_GREEN}INFO: (gitlab-docs): Stashing changes of gitlab-docs and syncing with upstream default branch..#{COLOR_CODE_RESET}" - system("git stash --quiet -u") if git_workdir_dirty? + system("git stash --quiet -u") if task_helpers.git_workdir_dirty? system("git checkout --quiet main") system("git fetch --quiet origin main") system("git reset --quiet --hard origin/main") - products.each_value do |product| + task_helpers.products.each_value do |product| # # Calculate new path from the redirect URL. # @@ -217,14 +219,14 @@ namespace :docs do content_dir = product['content_dir'] next unless Dir.exist?(content_dir) - default_branch = default_branch(product['repo']) + default_branch = task_helpers.default_branch(product['repo']) origin_default_branch = "origin/#{default_branch}" slug = product['slug'] counter = 0 Dir.chdir(content_dir) puts "\n#{COLOR_CODE_GREEN}INFO: (#{slug}): Stashing changes of #{slug} and syncing with upstream default branch..#{COLOR_CODE_RESET}" - system("git", "stash", "--quiet", "-u") if git_workdir_dirty? + system("git", "stash", "--quiet", "-u") if task_helpers.git_workdir_dirty? system("git", "checkout", "--quiet", default_branch) system("git", "fetch", "--quiet", "origin", default_branch) system("git", "reset", "--quiet", "--hard", origin_default_branch) diff --git a/content/_data/navigation.yaml b/content/_data/navigation.yaml index 05864f21..e4e6c867 100644 --- a/content/_data/navigation.yaml +++ b/content/_data/navigation.yaml @@ -142,17 +142,17 @@ sections: doc_url: 'omnibus/troubleshooting.html' # End of documentation from https://gitlab.com/gitlab-org/omnibus-gitlab - - doc_title: Cloud Native + - doc_title: Cloud-native GitLab doc_url: 'ee/install/cloud_native/' docs: # Documentation from https://gitlab.com/gitlab-org/charts/gitlab - - doc_title: Install with Helm Charts + - doc_title: Install with a Helm chart doc_url: 'charts/' docs: - doc_title: Install doc_url: 'charts/installation/' docs: - - doc_title: Required tools + - doc_title: Install prerequisites doc_url: 'charts/installation/tools.html' - doc_title: Cloud cluster preparation doc_url: 'charts/installation/cloud/' @@ -167,8 +167,11 @@ sections: doc_url: 'charts/installation/cloud/openshift.html' - doc_title: Oracle Container Engine for Kubernetes doc_url: 'charts/installation/cloud/oke.html' - - doc_title: Install with Helm Charts + - doc_title: Deploy the Helm chart doc_url: 'charts/installation/deployment.html' + docs: + - doc_title: Deployment options + doc_url: 'charts/installation/tools.html' - doc_title: Upgrade doc_url: 'charts/installation/upgrade.html' docs: @@ -1045,7 +1048,7 @@ sections: doc_url: 'ee/security/two_factor_authentication.html' - doc_title: User email confirmation doc_url: 'ee/security/user_email_confirmation.html' - - doc_title: Security of running jobs + - doc_title: Runners doc_url: 'runner/security/' - doc_title: Proxying assets doc_url: 'ee/security/asset_proxy.html' @@ -1761,8 +1764,6 @@ sections: doc_url: 'runner/executors/virtualbox.html' - doc_title: Configure runners doc_url: 'ee/ci/runners/configure_runners.html' - - doc_title: Secure runners - doc_url: 'runner/security/' - doc_title: Scale a fleet of runners doc_url: 'runner/fleet_scaling/' - doc_title: Best practices for large repositories @@ -1822,6 +1823,8 @@ sections: - category_title: Secure your application category_url: 'ee/user/application_security/' docs: + - doc_title: Get started + doc_url: 'ee/user/application_security/get-started-security.html' - doc_title: Security Configuration doc_url: 'ee/user/application_security/configuration/' - doc_title: Container Scanning diff --git a/doc/architecture.md b/doc/architecture.md index c545e1f0..4098a06c 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -82,6 +82,32 @@ The pipeline in the `gitlab-docs` project: - Builds and deploys the docs site itself. - Generates the review apps when the `review-docs-deploy` job is triggered. +### Pipeline configuration files + +The `gitlab-docs` project pipeline configuration is split into multiple files to +improve maintainability: + +- [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml): + The base configuration file contains: + - Global variables. + - [`workflow:rules`](https://docs.gitlab.com/ee/ci/yaml/index.html#workflowrules) + to limit which pipelines can run. + - External templates imported with [`include`](https://docs.gitlab.com/ee/ci/yaml/index.html#include). + - The other configuration files, also imported with `include`. +- [`.gitlab/ci/build-and-deploy.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/ci/build-and-deploy.gitlab-ci.yml): + The jobs that build the docs site before testing, and the jobs that deploy the site + or review apps. +- [`.gitlab/ci/docker-images.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/ci/docker-images.gitlab-ci.yml): + The jobs that build and test docker images. +- [`.gitlab/ci/rules.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/ci/rules.gitlab-ci.yml): + The [`rules`](https://docs.gitlab.com/ee/ci/yaml/index.html#rules), [`cache`](https://docs.gitlab.com/ee/ci/yaml/index.html#cache) + and other default configuration for most jobs in the pipeline. +- [`.gitlab/ci/security.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/ci/security.gitlab-ci.yml): + Extra configuration for security jobs to override their defaults and make them work + better in the pipeline. +- [`.gitlab/ci/test.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab/ci/test.gitlab-ci.yml): + Code tests and jobs used for [`gitlab-docs` maintenance](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks). + ### Rebuild the docs site Docker images Once a week on Mondays, a scheduled pipeline runs and rebuilds the Docker images diff --git a/lib/task_helpers.rb b/lib/task_helpers.rb index db988756..c532c883 100644 --- a/lib/task_helpers.rb +++ b/lib/task_helpers.rb @@ -2,89 +2,95 @@ require 'yaml' -PRODUCTS = %w[ee omnibus runner charts operator].freeze -VERSION_FORMAT = %r{^(?<major>\d{1,2})\.(?<minor>\d{1,2})$}.freeze +class TaskHelpers + PRODUCTS = %w[ee omnibus runner charts operator].freeze + VERSION_FORMAT = %r{^(?<major>\d{1,2})\.(?<minor>\d{1,2})$}.freeze -def config - # Parse the config file and create a hash. - @config ||= YAML.load_file('./nanoc.yaml') -end - -def products - return @products if defined?(@products) + def config + # Parse the config file and create a hash. + @config ||= YAML.load_file('./nanoc.yaml') + end - # Pull products data from the config. - @products = PRODUCTS.each_with_object({}) do |key, result| - result[key] = config['products'][key] + def products + @products ||= begin + # Pull products data from the config. + PRODUCTS.each_with_object({}) do |key, result| + result[key] = config['products'][key] + end + end end -end -def retrieve_branch(slug) - # If CI_COMMIT_REF_NAME is not defined (run locally), set it to the default branch. - if ENV["CI_COMMIT_REF_NAME"].nil? - default_branch(products[slug].fetch('repo')) - # If we're on a gitlab-docs stable branch according to the regex, catch the - # version and assign the product stable branches correctly. - elsif version = ENV["CI_COMMIT_REF_NAME"].match(VERSION_FORMAT) - case slug - # EE has different branch name scheme - when 'ee' - "#{version[:major]}-#{version[:minor]}-stable-ee" - when 'omnibus', 'runner' - "#{version[:major]}-#{version[:minor]}-stable" - # Charts don't use the same version scheme as GitLab, we need to - # deduct their version from the GitLab equivalent one. - when 'charts' - chart = chart_version(ENV["CI_COMMIT_REF_NAME"]).match(VERSION_FORMAT) - "#{chart[:major]}-#{chart[:minor]}-stable" - # If the upstream product doesn't follow a stable branch scheme, set the - # branch to the default - else + def retrieve_branch(slug) + # If CI_COMMIT_REF_NAME is not defined (run locally), set it to the default branch. + if ENV["CI_COMMIT_REF_NAME"].nil? default_branch(products[slug].fetch('repo')) + + # If we're on a gitlab-docs stable branch according to the regex, catch the + # version and assign the product stable branches correctly. + elsif version = ENV["CI_COMMIT_REF_NAME"].match(VERSION_FORMAT) + + case slug + # EE has different branch name scheme + when 'ee' + "#{version[:major]}-#{version[:minor]}-stable-ee" + + when 'omnibus', 'runner' + "#{version[:major]}-#{version[:minor]}-stable" + + # Charts don't use the same version scheme as GitLab, we need to + # deduct their version from the GitLab equivalent one. + when 'charts' + chart = chart_version(ENV["CI_COMMIT_REF_NAME"]).match(VERSION_FORMAT) + "#{chart[:major]}-#{chart[:minor]}-stable" + + # If the upstream product doesn't follow a stable branch scheme, set the + # branch to the default + else + default_branch(products[slug].fetch('repo')) + end + + # If we're NOT on a gitlab-docs stable branch, fetch the BRANCH_* environment + # variable, and if not assigned, set to the default branch. + else + ENV.fetch("BRANCH_#{slug.upcase}", default_branch(products[slug].fetch('repo'))) end - # If we're NOT on a gitlab-docs stable branch, fetch the BRANCH_* environment - # variable, and if not assigned, set to the default branch. - else - ENV.fetch("BRANCH_#{slug.upcase}", default_branch(products[slug].fetch('repo'))) end -end -def git_workdir_dirty? - status = `git status --porcelain` - !status.empty? -end + def git_workdir_dirty? + !`git status --porcelain`.empty? + end -def local_branch_exist?(branch) - status = `git branch --list #{branch}` - !status.empty? -end + def local_branch_exist?(branch) + !`git branch --list #{branch}`.empty? + end -# -# The charts versions do not follow the same GitLab major number, BUT -# they do follow a pattern https://docs.gitlab.com/charts/installation/version_mappings.html: -# -# 1. The minor version is the same for both -# 2. The major version augments for both at the same time -# -# This means we can deduct the charts version from the GitLab version, since -# the major charts version is always 9 versions behind its GitLab counterpart. -# -def chart_version(gitlab_version) - major, minor = gitlab_version.split('.') - - # Assume major charts version is nine less than major GitLab version. - # If this breaks and the version isn't found, it might be because they - # are no longer exactly 9 releases behind. Ask the distribution team - # about it. - major = major.to_i - 9 - - "#{major.to_s}.#{minor}" -end + # + # The charts versions do not follow the same GitLab major number, BUT + # they do follow a pattern https://docs.gitlab.com/charts/installation/version_mappings.html: + # + # 1. The minor version is the same for both + # 2. The major version augments for both at the same time + # + # This means we can deduct the charts version from the GitLab version, since + # the major charts version is always 9 versions behind its GitLab counterpart. + # + def chart_version(gitlab_version) + major, minor = gitlab_version.split('.') + + # Assume major charts version is nine less than major GitLab version. + # If this breaks and the version isn't found, it might be because they + # are no longer exactly 9 releases behind. Ask the distribution team + # about it. + major = major.to_i - 9 -def default_branch(repo) - # Get the URL-encoded path of the project - # https://docs.gitlab.com/ee/api/README.html#namespaced-path-encoding - url_encoded_path = repo.sub('https://gitlab.com/', '').sub('.git', '').gsub('/', '%2F') + "#{major}.#{minor}" + end - `curl --silent https://gitlab.com/api/v4/projects/#{url_encoded_path} | jq --raw-output .default_branch`.tr("\n", '') + def default_branch(repo) + # Get the URL-encoded path of the project + # https://docs.gitlab.com/ee/api/README.html#namespaced-path-encoding + url_encoded_path = repo.sub('https://gitlab.com/', '').sub('.git', '').gsub('/', '%2F') + + `curl --silent https://gitlab.com/api/v4/projects/#{url_encoded_path} | jq --raw-output .default_branch`.tr("\n", '') + end end diff --git a/spec/lib/task_helpers_spec.rb b/spec/lib/task_helpers_spec.rb new file mode 100644 index 00000000..5bf1a662 --- /dev/null +++ b/spec/lib/task_helpers_spec.rb @@ -0,0 +1,19 @@ +# frozen_string_literal: true + +require 'task_helpers' + +describe TaskHelpers do + describe '#chart_version' do + let(:gitlab_version) { nil } + + subject(:chart_version) { described_class.new.chart_version(gitlab_version) } + + context 'when GitLab version is 15' do + let(:gitlab_version) { '15.0' } + + it 'returns charts version 6.0' do + expect(chart_version).to eq('6.0') + end + end + end +end |