Commit e9442793 authored by Suzanne Selhorn's avatar Suzanne Selhorn

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

CTRT Revamp of CI/CD schedules documentation

See merge request gitlab-org/gitlab!81749
parents a2ceae05 ccb604dd
...@@ -71,6 +71,27 @@ Plan.default.actual_limits.update!(ci_needs_size_limit: 100) ...@@ -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`. 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 <!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues Include any troubleshooting steps that you can foresee. If you know beforehand what issues
......
...@@ -85,6 +85,28 @@ be triggered by the same event (a push to the source branch for an open merge re ...@@ -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) See how to [prevent duplicate pipelines](#avoid-duplicate-pipelines)
for more details. 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 ### Complex rules
You can use all `rules` keywords, like `if`, `changes`, and `exists`, in the same You can use all `rules` keywords, like `if`, `changes`, and `exists`, in the same
......
...@@ -169,7 +169,7 @@ job1: ...@@ -169,7 +169,7 @@ job1:
- if: '$CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_REF_NAME == "try-schedule-workflow"' - 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 #### Manual run
......
...@@ -8,140 +8,64 @@ type: reference, howto ...@@ -8,140 +8,64 @@ type: reference, howto
# Pipeline schedules **(FREE)** # Pipeline schedules **(FREE)**
Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository. Use scheduled pipelines to run GitLab CI/CD [pipelines](index.md) at regular intervals.
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).
## Prerequisites ## Prerequisites
In order for a scheduled pipeline to be created successfully: For a scheduled pipeline to run:
- 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
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 ## Run manually
message provides a link to the CI/CD Pipeline index page.
NOTE: To trigger a pipeline schedule manually, so that it runs immediately instead of
To help avoid abuse, users are rate limited to triggering a pipeline once per the next scheduled time:
minute.
### 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. ## Take ownership
The next time a pipeline is scheduled, your credentials are used.
![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 To take ownership of a pipeline created by a different user:
pipelines on the target branch, the schedule stops creating new
pipelines.
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. ## Related topics
- The target branch or tag is protected.
In this case, someone with sufficient privileges must take ownership of the - Pipeline schedules can be maintained by using the [Pipeline schedules API](../../api/pipeline_schedules.md).
schedule. - You can [control which jobs are added to scheduled pipelines](../jobs/job_control.md#run-jobs-for-scheduled-pipelines).
<!-- ## Troubleshooting <!-- ## Troubleshooting
......
...@@ -653,7 +653,7 @@ The order of precedence for variables is (from highest to lowest): ...@@ -653,7 +653,7 @@ The order of precedence for variables is (from highest to lowest):
1. These all have the same (highest) precedence: 1. These all have the same (highest) precedence:
- [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call). - [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). - [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). - Variables added when [creating a pipeline with the API](../../api/pipelines.md#create-a-new-pipeline).
1. Project [variables](#custom-cicd-variables). 1. Project [variables](#custom-cicd-variables).
......
...@@ -302,7 +302,7 @@ In `include` sections in your `.gitlab-ci.yml` file, you can use: ...@@ -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: In GitLab 14.5 and later, you can also use:
- [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call). - [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). - [Manual pipeline run variables](../variables/index.md#override-a-variable-when-running-a-pipeline-manually).
- Pipeline [predefined variables](../variables/predefined_variables.md). - Pipeline [predefined variables](../variables/predefined_variables.md).
......
...@@ -38,7 +38,10 @@ are valid: ...@@ -38,7 +38,10 @@ are valid:
- Run once a day at midnight: `0 0 * * *` - Run once a day at midnight: `0 0 * * *`
- Run once a week at midnight on Sunday morning: `0 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 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 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 For complete cron documentation, refer to the
[crontab(5) — Linux manual page](https://man7.org/linux/man-pages/man5/crontab.5.html). [crontab(5) — Linux manual page](https://man7.org/linux/man-pages/man5/crontab.5.html).
......
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