jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

improving cron syntax documentation (#57277)

Browse Source 
Co-authored-by: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com>
This commit is contained in:
Jenni C
2025-08-28 16:21:34 -07:00
committed by GitHub
parent 03da100a30
commit 2431a1b6d3
12 changed files with 66 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
content/actions/concepts/workflows-and-actions/notifications-for-workflow-runs.md
View File

@@ -10,6 +10,10 @@ redirect_from:
- /actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/notifications-for-workflow-runs
---
{% data reusables.actions.enterprise-github-hosted-runners %}
If you enable email or web notifications for {% data variables.product.prodname_actions %}, you'll receive a notification when any workflow runs that you've triggered have completed. The notification will include the workflow run's status (including successful, failed, neutral, and canceled runs). You can also choose to receive a notification only when a workflow run has failed. For more information about enabling or disabling notifications, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications).
{% data reusables.repositories.workflow-notifications %}
Notifications for scheduled workflows are sent to the user who initially created the workflow.
* If a different user updates the cron syntax, in the `schedule` event in the workflow file, subsequent notifications will be sent to that user instead.
* If a scheduled workflow is disabled and then re-enabled, notifications will be sent to the user who re-enabled the workflow rather than the user who last modified the cron syntax.
You can also see the status of workflow runs on a repository's Actions tab. For more information, see [AUTOTITLE](/actions/managing-workflow-runs).

60
content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md
View File

@@ -966,58 +966,44 @@ jobs:
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------|
| Not applicable | Not applicable | Last commit on default branch | Default branch | When the scheduled workflow is set to run. A scheduled workflow uses [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). For more information, see [AUTOTITLE](/actions/using-workflows#triggering-a-workflow-with-events). |
| Not applicable | Not applicable | Last commit on default branch | Default branch |
> [!NOTE]
> * {% data reusables.actions.schedule-delay %}
> * This event will only trigger a workflow run if the workflow file is on the default branch.
> * {% data reusables.actions.branch-requirement %}
> * Scheduled workflows will only run on the default branch.
> * In a public repository, scheduled workflows are automatically disabled when no repository activity has occurred in 60 days. For information on re-enabling a disabled workflow, see [AUTOTITLE](/enterprise-server/actions/using-workflows/disabling-and-enabling-a-workflow#enabling-a-workflow).
> * For an enterprise with {% data variables.product.prodname_emus %}, scheduled workflows will not run if the last `actor` associated with the scheduled workflow has been deprovisioned (and therefore become suspended) by the {% data variables.product.prodname_emu %} identity provider (IdP). However, if the last `actor` {% data variables.product.prodname_emu %} has not been deprovisioned by the IdP, and has only been removed as a member from a given organization in the enterprise, scheduled workflows will still run with that user set as the `actor`. Similarly, for an enterprise without {% data variables.product.prodname_emus %}, removing a user from an organization will not prevent scheduled workflows which had that user as their `actor` from running. Essentially, triggering a scheduled workflow requires that the status of the `actor` user account associated with the workflow is currently active (i.e. not suspended or deleted). Thus, the _user account's_ status, in both {% data variables.product.prodname_emu %} and non-{% data variables.product.prodname_emu %} scenarios, is what's important, _not_ the user's _membership status_ in the organization where the scheduled workflow is located.
> * Certain repository events change the `actor` associated with the workflow. For example, a user who changes the default branch of the repository, which changes the branch on which scheduled workflows run, becomes `actor` for those scheduled workflows.
> * For a deactivated scheduled workflow, if a user with `write` permissions to the repository makes a commit that changes the `cron` schedule on the workflow, the workflow will be reactivated, and that user will become the `actor` associated with any workflow runs. Note that, in this situation, the workflow is not reactivated by any change to the workflow file; you must alter the `cron` value in the workflow and commit this change.
>
> **Example:**
>
> ```yaml
> on:
> schedule:
> - cron: "15 4,5 * * *" # <=== Change this value
> ```
The `schedule` event allows you to trigger a workflow at a scheduled time.
**Example:**
```yaml
on:
schedule:
- cron: "15 4,5 * * *"
```
{% data reusables.repositories.actions-scheduled-workflow-example %}
Cron syntax has five fields separated by a space, and each field represents a unit of time.
```text
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
* * * * *
```
You can use these operators in any of the five fields:
| Operator | Description | Example |
| -------- | ----------- | ------- |
| * | Any value | `15 * * * *` runs at every minute 15 of every hour of every day. |
| , | Value list separator | `2,10 4,5 * * *` runs at minute 2 and 10 of the 4th and 5th hour of every day. |
| - | Range of values | `30 4-6 * * *` runs at minute 30 of the 4th, 5th, and 6th hour. |
| / | Step values | `20/15 * * * *` runs every 15 minutes starting from minute 20 through 59 (minutes 20, 35, and 50). |
> [!NOTE]
> {% data variables.product.prodname_actions %} does not support the non-standard syntax `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`, and `@reboot`.
You can use [crontab guru](https://crontab.guru/) to help generate your cron syntax and confirm what time it will run. To help you get started, there is also a list of [crontab guru examples](https://crontab.guru/examples.html).
Notifications for scheduled workflows are sent to the user who last modified the cron syntax in the workflow file. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/notifications-for-workflow-runs).
### `actor` for scheduled workflows
Certain repository events change the `actor` associated with the workflow. For example, a user who changes the default branch of the repository, which changes the branch on which scheduled workflows run, becomes `actor` for those scheduled workflows.
For a deactivated scheduled workflow, if a user with `write` permissions to the repository makes a commit that changes the `cron` schedule on the workflow, the workflow will be reactivated, and that user will become the `actor` associated with any workflow runs.
Notifications for scheduled workflows are sent to the user who last modified the cron syntax in the workflow file. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/notifications-for-workflow-runs).
> [!NOTE]
> For an enterprise with {% data variables.product.prodname_emus %}, triggering a scheduled workflow requires that the status of the `actor` user account associated with the workflow is currently active (i.e. not suspended or deleted).
> * Scheduled workflows will not run if the last `actor` associated with the scheduled workflow has been deprovisioned by the {% data variables.product.prodname_emu %} identity provider (IdP). However, if the last `actor` {% data variables.product.prodname_emu %} has not been deprovisioned by the IdP, and has only been removed as a member from a given organization in the enterprise, scheduled workflows will still run with that user set as the `actor`.
> * Similarly, for an enterprise without {% data variables.product.prodname_emus %}, removing a user from an organization will not prevent scheduled workflows which had that user as their `actor` from running.
> * Thus, the _user account's_ status, in both {% data variables.product.prodname_emu %} and non-{% data variables.product.prodname_emu %} scenarios, is what's important, _not_ the user's _membership status_ in the organization where the scheduled workflow is located.
## `status`

6
content/actions/reference/workflows-and-actions/workflow-syntax.md
View File

@@ -107,7 +107,11 @@ run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}
## `on.schedule`
{% data reusables.actions.workflows.section-triggering-a-workflow-schedule %}
You can use `on.schedule` to define a time schedule for your workflows.
{% data reusables.repositories.actions-scheduled-workflow-example %}
For more information about `schedule` events, see [AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule).
## `on.workflow_call`

2
content/actions/tutorials/migrate-to-github-actions/manual-migrations/migrate-from-jenkins.md
View File

@@ -126,6 +126,8 @@ on:
- cron: '*/15 * * * 1-5'
```
For more information about `schedule` events and accepted cron syntax, see [AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule).
### Configuring environment variables in a pipeline
#### Jenkins pipeline with an environment variable

2
content/actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets.md
View File

@@ -249,7 +249,7 @@ ARC supports using anonymous or authenticated proxies. If you use authenticated
The `maxRunners` and `minRunners` properties provide you with a range of options to customize your ARC setup.
> [!NOTE]
> ARC does not support scheduled maximum and minimum configurations. You can use a cronjob or any other scheduling solution to update the configuration on a schedule.
> ARC does not support scheduled maximum and minimum configurations. You can use a cron job or any other scheduling solution to update the configuration on a schedule.
#### Example: Unbounded number of runners

4
content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.md
View File

@@ -103,10 +103,10 @@ For more information about using `on:pull_request:paths-ignore` and `on:pull_req
### Scanning on a schedule
If you use the default {% data variables.code-scanning.codeql_workflow %}, the workflow will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the `cron` value in the workflow. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onschedule).
If you use the default {% data variables.code-scanning.codeql_workflow %}, the workflow will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the `cron` value for the `on.schedule` event in the workflow. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-syntax#onschedule).
> [!NOTE]
> {% data variables.product.prodname_dotcom %} only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch.
> {% data reusables.actions.branch-requirement %}
### Example

2
content/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates.md
View File

@@ -27,7 +27,7 @@ There are a couple of customization options you can implement to optimize {% dat
## Controlling the frequency and timings of dependency updates
{% data variables.product.prodname_dependabot %} runs its checks for version updates at a frequency set by you in the configuration file, where the required field, `schedule.interval`, must be set to `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `yearly`, or `cron` (see [cronjob](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#cronjob)).
{% data variables.product.prodname_dependabot %} runs its checks for version updates at a frequency set by you in the configuration file, where the required field, `schedule.interval`, must be set to `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `yearly`, or `cron` (see [`cronjob`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#cronjob)).
By default, {% data variables.product.prodname_dependabot %} balances its workload by assigning a random time to check and raise pull requests for dependency updates.

11
content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md
View File

@@ -634,17 +634,12 @@ Optionally, run all updates for a package manager at a specific time of day. By
### `cronjob`
Supported values: Valid cron expression in cron format or natural expression.
Supported values: Valid cron expression in cron syntax or natural expression.
{% data reusables.repositories.cron %}
Examples : `0 9 * * *`, `every day at 5pm`
cron format is defined as the following:
* `*` The minute field.
* `*` The hour field (in 24-hour time).
* `*` The day of the month (matches any day of the month).
* `*` The month (matches any month).
* `*` The day of the week (matches any day of the week).
`0 9 * * *` is equivalent to "every day at 9am". `every day at 5pm` is equivalent to `0 17 * * *`.
> [!NOTE]

3
data/reusables/actions/workflows/section-triggering-a-workflow-schedule.md
View File

@@ -1,3 +0,0 @@
You can use `on.schedule` to define a time schedule for your workflows. {% data reusables.repositories.actions-scheduled-workflow-example %}
For more information about cron syntax, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#scheduled-events).

22
data/reusables/repositories/actions-scheduled-workflow-example.md
View File

@@ -1,21 +1,23 @@
You can schedule a workflow to run at specific UTC times using [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.
Use [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07) to schedule workflows to run at specific UTC times. Scheduled workflows run on the latest commit on the default branch. The shortest interval you can run scheduled workflows is once every 5 minutes.
This example triggers the workflow every day at 5:30 and 17:30 UTC:
{% data reusables.repositories.cron %}
```yaml
on:
schedule:
# * is a special character in YAML so you have to quote this string
- cron: '30 5,17 * * *'
```
You can use these operators in any of the five fields:
A single workflow can be triggered by multiple `schedule` events. You can access the schedule event that triggered the workflow through the `github.event.schedule` context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the `Not on Monday or Wednesday` step on Monday and Wednesday.
| Operator | Description | Example |
| -------- | ----------- | ------- |
| * | Any value | `15 * * * *` runs at every minute 15 of every hour of every day. |
| , | Value list separator | `2,10 4,5 * * *` runs at minute 2 and 10 of the 4th and 5th hour of every day. |
| - | Range of values | `30 4-6 * * *` runs at minute 30 of the 4th, 5th, and 6th hour. |
| / | Step values | `20/15 * * * *` runs every 15 minutes starting from minute 20 through 59 (minutes 20, 35, and 50). |
A single workflow can be triggered by multiple `schedule` events. Access the `schedule` event that triggered the workflow through the `github.event.schedule` context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, and 17:30 UTC on Tuesdays and Thursdays, but skips the `Not on Monday or Wednesday` step on Monday and Wednesday.
```yaml
on:
schedule:
- cron: '30 5 * * 1,3'
- cron: '30 5 * * 2,4'
- cron: '30 5,17 * * 2,4'
jobs:
test_schedule:

11
data/reusables/repositories/cron.md Normal file
View File

@@ -0,0 +1,11 @@
Cron syntax has five fields separated by a space, and each field represents a unit of time.
```text
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
* * * * *
```

5
data/reusables/repositories/workflow-notifications.md
View File

@@ -1,5 +0,0 @@
If you enable email or web notifications for {% data variables.product.prodname_actions %}, you'll receive a notification when any workflow runs that you've triggered have completed. The notification will include the workflow run's status (including successful, failed, neutral, and canceled runs). You can also choose to receive a notification only when a workflow run has failed. For more information about enabling or disabling notifications, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications).
Notifications for scheduled workflows are sent to the user who initially created the workflow. If a different user updates the cron syntax in the workflow file, subsequent notifications will be sent to that user instead. If a scheduled workflow is disabled and then re-enabled, notifications will be sent to the user who re-enabled the workflow rather than the user who last modified the cron syntax.
You can also see the status of workflow runs on a repository's Actions tab. For more information, see [AUTOTITLE](/actions/managing-workflow-runs).