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 at specific intervals. For example:
- Every month on the 22nd for a certain branch.
- Once every day.
In addition to using the GitLab UI, pipeline schedules can be maintained using the Pipeline schedules API.
Schedule timing is configured with cron notation, parsed by Fugit.
In order for a scheduled pipeline to be created successfully:
- The schedule owner must have permissions 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:
- Navigate to the project's CI / CD > Schedules page.
- Click the New schedule button.
- Fill in the Schedule a new pipeline form.
- Click the Save pipeline schedule button.
NOTE: Pipelines execution timing is dependent 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.
Introduced in GitLab 9.4.
You can pass any number of arbitrary variables. They are available in
GitLab CI/CD so that they can be used in your
Using only and except
To configure a job to be executed only when the pipeline has been scheduled (or the opposite), use only and except configuration keywords.
job:on-schedule: only: - schedules script: - make world job: except: - schedules script: - make build
The pipelines are not executed exactly on schedule because schedules are handled by Sidekiq, which runs according to its interval.
For example, only two pipelines are created per day if:
- 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:
- Edit the
gitlab_rails['pipeline_schedule_worker_cron']value in your instance's
- Reconfigure GitLab for the changes to take effect.
For GitLab.com, refer to the dedicated settings page.
Working with scheduled pipelines
After configuration, GitLab supports many functions for working with scheduled pipelines.
Introduced in GitLab 10.4.
To trigger a pipeline schedule manually, click the "Play" button:
This schedules a background job to run the pipeline schedule. A flash message provides a link to the CI/CD Pipeline index page.
NOTE: To help avoid abuse, users are rate limited to triggering a pipeline once per minute.
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. The next time a pipeline is scheduled, your credentials are used.
If the owner of a pipeline schedule cannot create pipelines on the target branch, the schedule stops creating new pipelines.
This can happen if, for example:
- The owner is blocked or removed from the project.
- The target branch or tag is protected.
In this case, someone with sufficient privileges must take ownership of the schedule.