gitlab-org--gitlab-foss/doc/user/project/pipelines/schedules.md

121 lines
4.1 KiB
Markdown
Raw Normal View History

# Pipeline schedules
2017-05-18 06:55:29 -04:00
> **Notes**:
2019-03-20 09:45:15 -04:00
>
2019-04-01 19:15:46 -04:00
> - Introduced in GitLab 9.1 as [Trigger Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533).
> - [Renamed to Pipeline Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10853) in GitLab 9.2.
> - Cron notation is parsed by [Fugit](https://github.com/floraison/fugit).
2017-05-18 06:55:29 -04:00
2019-04-01 19:15:46 -04:00
Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
2017-05-18 06:55:29 -04:00
2019-04-01 19:15:46 -04:00
Pipeline schedules can be used to also run [pipelines](../../../ci/pipelines.md) at specific intervals. For example:
2017-05-18 06:55:29 -04:00
2019-04-01 19:15:46 -04:00
- Every month on the 22nd for a certain branch.
- Once every day.
2017-05-18 06:55:29 -04:00
2019-04-01 19:15:46 -04:00
In addition to using the GitLab UI, pipeline schedules can be maintained using the
[Pipeline schedules API](../../../api/pipeline_schedules.md).
## 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.
2017-05-18 06:55:29 -04:00
![New Schedule Form](img/pipeline_schedules_new_form.png)
2019-04-01 19:15:46 -04:00
NOTE: **Note:**
Pipelines execution [timing is dependent](#advanced-configuration) on Sidekiq's own schedule.
2017-05-18 06:55:29 -04:00
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)
2019-04-01 19:15:46 -04:00
### Using variables
2019-04-01 19:15:46 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12328) in GitLab 9.4.
You can pass any number of arbitrary variables and they will be available in
2019-04-01 19:15:46 -04:00
GitLab CI so that they can be used in your [`.gitlab-ci.yml` file](../../../ci/yaml/README.md).
![Scheduled pipeline variables](img/pipeline_schedule_variables.png)
2019-04-01 19:15:46 -04:00
### Using only and except
2017-06-12 03:16:38 -04:00
To configure that a job can be executed only when the pipeline has been
scheduled (or the opposite), you can use
[only and except](../../../ci/yaml/README.md#onlyexcept-basic) configuration keywords.
2017-06-12 03:16:38 -04:00
2019-04-01 19:15:46 -04:00
For example:
```yaml
2017-06-12 03:16:38 -04:00
job:on-schedule:
only:
- schedules
script:
- make world
job:
except:
- schedules
script:
- make build
```
2019-04-01 19:15:46 -04:00
### Advanced configuration
The pipelines won't be executed exactly on schedule because schedules are handled by
Sidekiq, which runs according to its interval.
For example, only two pipelines will be created per day if:
2017-05-18 06:55:29 -04:00
2019-04-01 19:15:46 -04:00
- You set a schedule to create a pipeline every minute (`* * * * *`).
- The Sidekiq worker runs on 00:00 and 12:00 every day (`0 */12 * * *`).
To change the Sidekiq worker's frequency:
1. Edit the `gitlab_rails['pipeline_schedule_worker_cron']` value in your instance's `gitlab.rb` file.
2019-04-01 19:15:46 -04:00
1. [Restart GitLab](../../../administration/restart_gitlab.md).
For GitLab.com, refer to the [dedicated settings page](../../gitlab_com/index.md#cron-jobs).
## Working with scheduled pipelines
Once configured, GitLab supports many functions for working with scheduled pipelines.
### Running manually
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15700) in GitLab 10.4.
To trigger a pipeline schedule manually, click the "Play" button:
![Play Pipeline Schedule](img/pipeline_schedule_play.png)
This will schedule a background job to run the pipeline schedule. A flash
message will provide a link to the CI/CD Pipeline index page.
NOTE: **Note:**
To help avoid abuse, users are rate limited to triggering a pipeline once per
minute.
### Taking ownership
Pipelines are executed as a user, who owns a schedule. This influences what projects and other resources the pipeline has access to.
If a user does not own a pipeline, you can take ownership by clicking the **Take ownership** button.
2017-05-18 06:55:29 -04:00
The next time a pipeline is scheduled, your credentials will be used.
![Schedules list](img/pipeline_schedules_ownership.png)
Squashed commit of the following: commit 0c00e52d339f8471a6ea425d5a4a59751a3f4a35 Author: Shinya Maeda <shinya@gitlab.com> Date: Fri Nov 30 15:41:46 2018 +0900 Update schedules.md commit 0ae56bf5a0ba9254d2ebd4c846395113ae72d686 Merge: c143777c9f2 9ce28bf08b7 Author: Shinya Maeda <shinya@gitlab.com> Date: Fri Nov 30 15:38:01 2018 +0900 Merge branch 'master-ce' into ignore-failed-pipeline-creation-on-pipeline-schedule commit c143777c9f250c8075355ac07e9bae7b074665c3 Author: Shinya Maeda <shinya@gitlab.com> Date: Thu Nov 29 17:18:07 2018 +0900 Fix coding offence commit 7c816dfa634b5911310c67c285fc3c37d5f03517 Author: Shinya Maeda <shinya@gitlab.com> Date: Thu Nov 29 16:12:06 2018 +0900 Improve spec quality commit f78eed45e991123f8af4a7b24f041529bbb35e91 Merge: 96d20ce9144 a5f4627857b Author: Shinya Maeda <shinya@gitlab.com> Date: Thu Nov 29 15:20:16 2018 +0900 Merge branch 'master-ce' into ignore-failed-pipeline-creation-on-pipeline-schedule commit 96d20ce914458f86e68b57bc1bb88ab8d27f010b Author: Shinya Maeda <shinya@gitlab.com> Date: Tue Nov 27 16:25:42 2018 +0900 Print pipeline error commit 97842068b6cf1432cd400ead749843946b4f51ee Merge: c2b015949af 2ee8c40fc16 Author: Shinya Maeda <shinya@gitlab.com> Date: Tue Nov 27 15:51:49 2018 +0900 Merge branch 'master-ce' into ignore-failed-pipeline-creation-on-pipeline-schedule commit c2b015949afb3ecc70cb057e2d13672f378c0d03 Merge: 3435137c17b fbbe5ccd1be Author: Shinya Maeda <shinya@gitlab.com> Date: Mon Nov 26 15:26:17 2018 +0900 Merge branch 'master-ce' into ignore-failed-pipeline-creation-on-pipeline-schedule commit 3435137c17b0ef03003e39dd08c7370fe916c626 Author: Shinya Maeda <shinya@gitlab.com> Date: Tue Nov 20 17:45:38 2018 +0900 Track exception with Sentry commit 3f01f10d3b7380f0e8ceb3a379d8b6c602e9d6ca Merge: 5749c62355f 8a581d531ba Author: Shinya Maeda <shinya@gitlab.com> Date: Tue Nov 20 17:12:41 2018 +0900 Merge branch 'master-ce' into ignore-failed-pipeline-creation-on-pipeline-schedule commit 5749c62355f8de62bb4e36ba1e351a78350607c1 Author: Shinya Maeda <shinya@gitlab.com> Date: Thu Nov 1 11:14:26 2018 +0900 Create a pipeline even if it is corrupted commit e01789890b6949b346d40fadef41aa133191cc43 Author: Shinya Maeda <shinya@gitlab.com> Date: Wed Oct 31 14:26:09 2018 +0900 Improve production log message commit f20d698a535f1dc70d5437c20b629fd1d956fb27 Author: Shinya Maeda <shinya@gitlab.com> Date: Fri Oct 19 17:11:20 2018 +0900 Fix typo commit 01323b02ac41ec50bcf237409f2e3c5c214bbfc1 Author: Shinya Maeda <shinya@gitlab.com> Date: Thu Oct 18 14:46:44 2018 +0900 Update documents commit 460337bf4a7e67a35d6c342678b4cfe66710ad56 Author: Shinya Maeda <shinya@gitlab.com> Date: Wed Oct 10 13:21:26 2018 +0900 Add changelog commit a3c4711752fedebfacbdf52da94058524af3c9f4 Author: Shinya Maeda <shinya@gitlab.com> Date: Wed Oct 10 09:20:06 2018 +0900 Ignore failed pipeline creation in pipeline schedule worker. Instead, logging the event.
2018-11-30 02:32:30 -05:00
NOTE: **Note:**
If the owner of a pipeline schedule doesn't have the ability to create pipelines
on the target branch, the schedule will stop creating new pipelines. This can
happen if, for example, the owner is blocked or removed from the project, or
the target branch or tag is protected. In this case, someone with sufficient
privileges must take ownership of the schedule.