diff options
Diffstat (limited to 'doc/ci/pipelines/schedules.md')
| -rw-r--r-- | doc/ci/pipelines/schedules.md | 159 |
1 files changed, 43 insertions, 116 deletions
diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index fe9db3306cd..8813f3e1d59 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -6,142 +6,69 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/schedules. type: reference, howto --- -# Pipeline schedules **(FREE)** +# Scheduled pipelines **(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. - - - -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. - - - -### 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). - - - -### 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). +For a scheduled pipeline to run: -## 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. -After configuration, GitLab supports many functions for working with scheduled pipelines. +Otherwise, the pipeline is not created. No error message is displayed. -### Running manually +## Add a pipeline schedule -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15700) in GitLab 10.4. +> Scheduled pipelines for tags [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23292) in GitLab 14.9. -To trigger a pipeline schedule manually, click the "Play" button: +To add a pipeline schedule: - +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). + - **Target branch or tag**: Select the branch or tag for the pipeline. + - **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 - +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 |