Merge branch 'docs-pipeline-schedules-ctrt' into 'master'

CTRT Revamp of CI/CD schedules documentation

See merge request gitlab-org/gitlab!81749

doc/administration/cicd.md

@@ -71,6 +71,27 @@ Plan.default.actual_limits.update!(ci_needs_size_limit: 100)
 
 To disable directed acyclic graphs (DAG), set the limit to `0`.
 
+## Change maximum scheduled pipeline frequency
+
+[Scheduled pipelines](../ci/pipelines/schedules.md) can be configured with any [cron value](../topics/cron/index.md),
+but they do not always run exactly when scheduled. An internal process, called the
+_pipeline schedule worker_, queues all the scheduled pipelines, but does not
+run continuously. The worker runs on its own schedule, and scheduled pipelines that
+are ready to start are only queued the next time the worker runs. Scheduled pipelines
+can't run more frequently than the worker.
+
+The default frequency of the pipeline schedule worker is `3-59/10 * * * *` (every ten minutes,
+starting with `0:03`, `0:13`, `0:23`, and so on). The default frequency for GitLab.com
+is listed in the [GitLab.com settings](../user/gitlab_com/index.md#gitlab-cicd).
+
+To change the frequency of the pipeline schedule worker:
+
+1. Edit the `gitlab_rails['pipeline_schedule_worker_cron']` value in your instance's `gitlab.rb` file.
+1. [Reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+
+For example, to set the maximum frequency of pipelines to twice a day, set `pipeline_schedule_worker_cron`
+to a cron value of `0 */12 * * *` (`00:00` and `12:00` every day).
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues

doc/ci/jobs/job_control.md

@@ -85,6 +85,28 @@ be triggered by the same event (a push to the source branch for an open merge re
 See how to [prevent duplicate pipelines](#avoid-duplicate-pipelines)
 for more details.
 
+#### Run jobs for scheduled pipelines
+
+To configure a job to be executed only when the pipeline has been
+scheduled, use the [`rules`](../yaml/index.md#rules) keyword.
+
+In this example, `make world` runs in scheduled pipelines, and `make build`
+runs in branch and tag pipelines:
+
+```yaml
+job:on-schedule:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  script:
+    - make world
+
+job:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "push"
+  script:
+    - make build
+```
+
 ### Complex rules
 
 You can use all `rules` keywords, like `if`, `changes`, and `exists`, in the same

doc/ci/migration/circleci.md

@@ -169,7 +169,7 @@ job1:
     - if: '$CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_REF_NAME == "try-schedule-workflow"'
 ```
 
-After the pipeline configuration is saved, you configure the cron schedule in the [GitLab UI](../pipelines/schedules.md#configuring-pipeline-schedules), and can enable or disable schedules in the UI as well.
+After the pipeline configuration is saved, you configure the cron schedule in the [GitLab UI](../pipelines/schedules.md#add-a-pipeline-schedule), and can enable or disable schedules in the UI as well.
 
 #### Manual run
 

doc/ci/pipelines/schedules.md

@@ -8,140 +8,64 @@ type: reference, howto
 
 # Pipeline schedules **(FREE)**
 
-Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
-
-Pipeline schedules can be used to also run [pipelines](index.md) at specific intervals. For example:
-
-- Every month on the 22nd (cron example: `0 0 22 * *`) for a certain branch.
-- Every month on the 2nd Monday (cron example: `0 0 * * 1#2`).
-- Every other Sunday at 0900 hours (cron example: `0 9 * * sun%2`).
-- Once every day (cron example: `0 0 * * *`).
-
-Schedule timing is configured with [cron notation](../../topics/cron/index.md).
-You can use any cron value, but scheduled pipelines cannot run more frequently
-than the instance's [maximum frequency for scheduled pipelines](#advanced-configuration).
-
-In addition to using the GitLab UI, pipeline schedules can be maintained using the
-[Pipeline schedules API](../../api/pipeline_schedules.md).
+Use scheduled pipelines to run GitLab CI/CD [pipelines](index.md) at regular intervals.
 
 ## Prerequisites
 
-In order for a scheduled pipeline to be created successfully:
-
-- The schedule owner must have [permissions](../../user/permissions.md) to merge into the target branch.
-- The pipeline configuration must be valid.
-
-Otherwise the pipeline is not created.
-
-## Configuring pipeline schedules
-
-To schedule a pipeline for project:
-
-1. Navigate to the project's **CI/CD > Schedules** page.
-1. Click the **New schedule** button.
-1. Fill in the **Schedule a new pipeline** form.
-1. Click the **Save pipeline schedule** button.
-
-![New Schedule Form](img/pipeline_schedules_new_form.png)
-
-NOTE:
-Pipelines execution [timing is dependent](#advanced-configuration) on Sidekiq's own schedule.
-
-In the **Schedules** index page you can see a list of the pipelines that are
-scheduled to run. The next run is automatically calculated by the server GitLab
-is installed on.
-
-![Schedules list](img/pipeline_schedules_list.png)
-
-### Using variables
-
-You can pass any number of arbitrary variables. They are available in
-GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/yaml/index.md).
-
-![Scheduled pipeline variables](img/pipeline_schedule_variables.png)
-
-### Using `rules`
-
-To configure a job to be executed only when the pipeline has been
-scheduled, use the [`rules`](../yaml/index.md#rules) keyword.
-
-In this example, `make world` runs in scheduled pipelines, and `make build`
-runs in branch and tag pipelines:
-
-```yaml
-job:on-schedule:
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "schedule"
-  script:
-    - make world
-
-job:
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "push"
-  script:
-    - make build
-```
-
-### Advanced configuration **(FREE SELF)**
-
-Scheduled pipelines can be configured with any [cron value](../../topics/cron/index.md),
-but they do not always run exactly when scheduled. An internal process, called the
-_pipeline schedule worker_, queues all the scheduled pipelines, but does not
-run continuously. The worker runs on its own schedule, and scheduled pipelines that
-are ready to start are only queued the next time the worker runs. Scheduled pipelines
-can't run more frequently than the worker.
-
-The default frequency of the pipeline schedule worker is `3-59/10 * * * *` (every ten minutes,
-starting with `0:03`, `0:13`, `0:23`, and so on). The default frequency for GitLab.com
-is listed in the [GitLab.com settings](../../user/gitlab_com/index.md#gitlab-cicd).
-
-To change the frequency of the pipeline schedule worker:
-
-1. Edit the `gitlab_rails['pipeline_schedule_worker_cron']` value in your instance's `gitlab.rb` file.
-1. [Reconfigure GitLab](../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
-
-For example, to set the maximum frequency of pipelines to twice a day, set `pipeline_schedule_worker_cron`
-to a cron value of `0 */12 * * *` (`00:00` and `12:00` every day).
-
-## Working with scheduled pipelines
+For a scheduled pipeline to run:
 
-After configuration, GitLab supports many functions for working with scheduled pipelines.
+- The schedule owner must have the Developer role. For pipelines on protected branches,
+  the schedule owner must be [allowed to merge](../../user/project/protected_branches.md#configure-a-protected-branch)
+  to the branch.
+- The [CI/CD configuration](../yaml/index.md) must be valid.
 
-### Running manually
+Otherwise, the pipeline is not created. No error message is displayed.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15700) in GitLab 10.4.
+## Add a pipeline schedule
 
-To trigger a pipeline schedule manually, click the "Play" button:
+To add a pipeline schedule:
 
-![Play Pipeline Schedule](img/pipeline_schedule_play.png)
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **CI/CD > Schedules**.
+1. Select **New schedule** and fill in the form.
+   - **Interval Pattern**: Select one of the preconfigured intervals, or enter a custom
+     interval in [cron notation](../../topics/cron/index.md). You can use any cron value,
+     but scheduled pipelines cannot run more frequently than the instance's
+     [maximum scheduled pipeline frequency](../../administration/cicd.md#change-maximum-scheduled-pipeline-frequency).
+   - **Variables**: Add any number of [CI/CD variables](../variables/index.md) to the schedule.
+     These variables are available only when the scheduled pipeline runs,
+     and not in any other pipeline run.
 
-This schedules a background job to run the pipeline schedule. A flash
-message provides a link to the CI/CD Pipeline index page.
+## Run manually
 
-NOTE:
-To help avoid abuse, users are rate limited to triggering a pipeline once per
-minute.
+To trigger a pipeline schedule manually, so that it runs immediately instead of
+the next scheduled time:
 
-### Taking ownership
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **CI/CD > Schedules**.
+1. On the right of the list, for
+   the pipeline you want to run, select **Play** (**{play}**).
 
-Pipelines are executed as a user, who owns a schedule. This influences what projects and other resources the pipeline has access to.
+You can manually run scheduled pipelines once per minute.
 
-If a user does not own a pipeline, you can take ownership by clicking the **Take ownership** button.
-The next time a pipeline is scheduled, your credentials are used.
+## Take ownership
 
-![Schedules list](img/pipeline_schedules_ownership.png)
+Scheduled pipelines execute with the permissions of the user
+who owns the schedule. The pipeline has access to the same resources as the pipeline owner,
+including [protected environments](../environments/protected_environments.md) and the
+[CI/CD job token](../jobs/ci_job_token.md).
 
-If the owner of a pipeline schedule cannot create
-pipelines on the target branch, the schedule stops creating new
-pipelines.
+To take ownership of a pipeline created by a different user:
 
-This can happen if, for example:
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **CI/CD > Schedules**.
+1. On the right of the list, for
+   the pipeline you want to become owner of, select **Take ownership**.
 
-- The owner is blocked or removed from the project.
-- The target branch or tag is protected.
+## Related topics
 
-In this case, someone with sufficient privileges must take ownership of the
-schedule.
+- Pipeline schedules can be maintained by using the [Pipeline schedules API](../../api/pipeline_schedules.md).
+- You can [control which jobs are added to scheduled pipelines](../jobs/job_control.md#run-jobs-for-scheduled-pipelines).
 
 <!-- ## Troubleshooting
 

doc/ci/variables/index.md

@@ -653,7 +653,7 @@ The order of precedence for variables is (from highest to lowest):
 
 1. These all have the same (highest) precedence:
    - [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call).
-   - [Scheduled pipeline variables](../pipelines/schedules.md#using-variables).
+   - [Scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule).
    - [Manual pipeline run variables](#override-a-variable-when-running-a-pipeline-manually).
    - Variables added when [creating a pipeline with the API](../../api/pipelines.md#create-a-new-pipeline).
 1. Project [variables](#custom-cicd-variables).

doc/ci/yaml/includes.md

@@ -302,7 +302,7 @@ In `include` sections in your `.gitlab-ci.yml` file, you can use:
 In GitLab 14.5 and later, you can also use:
 
 - [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call).
-- [Scheduled pipeline variables](../pipelines/schedules.md#using-variables).
+- [Scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule).
 - [Manual pipeline run variables](../variables/index.md#override-a-variable-when-running-a-pipeline-manually).
 - Pipeline [predefined variables](../variables/predefined_variables.md).
 

doc/topics/cron/index.md

@@ -38,7 +38,10 @@ are valid:
 - Run once a day at midnight: `0 0 * * *`
 - Run once a week at midnight on Sunday morning: `0 0 * * 0`
 - Run once a month at midnight of the first day of the month: `0 0 1 * *`
+- Run once a month on the 22nd: `0 0 22 * *`)
+- Run once a month on the 2nd Monday: `0 0 * * 1#2`
 - Run once a year at midnight of 1 January: `0 0 1 1 *`
+- Run every other Sunday at 0900 hours: `0 9 * * sun%2`
 
 For complete cron documentation, refer to the
 [crontab(5) — Linux manual page](https://man7.org/linux/man-pages/man5/crontab.5.html).