Scheduled activities
About scheduled activities
Both changes and workflow runs can be scheduled to run on a future date and configured to run on a repeated schedule. This is referred to as a scheduled activity.
Scheduled activities are configured in MintPress to automatically create and deploy changes or workflow runs in a project, environment or asset:
- once, at a date and time you pick
- repeatedly, on a cron schedule
- in response to project Git repository updates (scheduled changes only)
Understanding the scheduled activity screen
A table view is presented upon accessing the scheduled activity screen. This view organises scheduled changes and scheduled workflows, allowing users to track, review, and manage upcoming activities.
Scheduled activity details
Each row includes:
| Column | Description |
|---|---|
| Project, Environment, Asset | Where the activity is scheduled to run. An activity scheduled against a project or environment shows - in the columns below it. Only the levels beneath the one you are viewing are shown, so an environment's tab shows only Asset. |
| Action | The action a scheduled change runs, or the code of the workflow a scheduled workflow run runs. |
| Labels | The labels given to the scheduled activity. |
| Trigger | How the schedule is triggered, either Scheduled or Commit dependent (via a new commit). |
| Next run at | Timestamp for when the activity is next scheduled to run. |
| Repeats | Whether the scheduled activity is recurring or will run only once. |
| Enabled | Whether the scheduled activity is enabled. It shows as disabled while its parent, Git remote, workflow or workflow version is archived. Restoring that re-enables it only if you had not disabled it yourself. A scheduled activity you disable stays disabled when you edit it. |
| Scheduled by | The user who scheduled the activity. |
| Created at | Timestamp for when the scheduled activity was created. |
Buttons & links
| Buttons & links | Function |
|---|---|
| Bulk actions | Change the schedule of, enable, disable or delete multiple scheduled activities. |
| Search bar | Filter the contents of the table based on these criteria. |
| Filters | Filter by Enabled (enabled or disabled), Type, Trigger, Repeats, Scheduled by and Next run. Filters that do not fit on the toolbar move under More, which also holds the Created at, Ends at, Git rev, Metadata and Labels filters, and Include archived. |
| Columns | Hide or display columns in the table. |
Click a row to open the scheduled activity's details page.
A project's or environment's Scheduled activity tab also lists the scheduled activities of the environments and assets beneath it, and the Environment and Asset columns show which one each belongs to. Untick Include children on the toolbar to list only the node's own. A workflow's tab lists only the scheduled runs of that workflow.
Archived scheduled activities
Archived scheduled activities are left out of the table by default. A scheduled activity counts as archived when the project, environment or asset it belongs to is archived (or belongs to one that is), when a scheduled change's Git remote is archived, or when a scheduled workflow run's workflow, or the workflow version it is pinned to, is archived.
To list them alongside active scheduled activities, open More, tick Include archived and click Apply. Clear hides them again. Viewed under an archived project, environment, asset or workflow, every scheduled activity is archived, so the table lists them all and Include archived is not offered.
Triggering on new commits only
When creating a scheduled change, you can decide whether it only creates a change if there are new commits in the Git repository since the previous run.
| New commits only | Git revision has new commits | MintPress change created |
|---|---|---|
| true | true | true |
| true | false | false |
| false | n/a | true |
If the current commit on the relevant Git revision (for example master) hasn't been used in a change for the chosen action and target, then a new change will be created straight away as part of this scheduled change.
It can take a minute for MintPress to detect Git updates and create the new change.
As more commits are added to the Git repository, new changes will be created. Scheduled changes poll the project's Git repository for new commits on the Git revision. If multiple commits occur on the relevant Git revision between polls then only one scheduled change will be created with the latest commit.
Limiting a scheduled change to particular files
A scheduled change that triggers on new commits only creates a change for every new commit, whatever that commit touched. Commit file patterns narrow it to commits that changed the files you care about, so a schedule that deploys can ignore a commit that only edited documentation.
Patterns are set under Run only when matching files have changed in the Schedule panel of the run change dialog, as a row per glob with a Negate column and a match mode of ALL or ANY. Over the API they are supplied as commit_file_patterns when creating or updating a scheduled change:
curl --fail --user {{username}}:{{password}} http://<host>/api/scheduled_activities -H 'content-type: application/vnd.api+json' \
-d '{ "data": { "attributes": { "parent_path": "/projects/bank/assets/simple_sn", "action": "deploy", "cron_schedule": "*/5 * * * *", "repeat": true, "new_commits_only": true, "commit_file_patterns": [{ "match": "**/*.md", "negate": true }] } } }'
Each pattern is an object carrying a match glob and an optional negate flag, which defaults to false. Patterns describe what changed between two commits, so they require new_commits_only - supplying them without it is rejected with can only be supplied when new_commits_only is enabled.
A scheduled change accepts up to 20 patterns, each glob up to 500 characters, and 1000 bytes of globs across all of them. MintPress stores them sorted and de-duplicated, so the response to your request can list them in a different order to the one you sent.
Pattern syntax
Globs are matched against each path a commit changed, relative to the root of the repository. * and ? match within a single path segment, and **/ crosses directories. Alternatives in braces and character classes in brackets both work. A file whose name begins with a . is matched like any other.
| Glob | Matches | Does not match |
|---|---|---|
**/*.rb | actions.rb, lib/deploy.rb | README.md |
docs/* | docs/index.md | docs/api/v1.md |
docs/**/* | docs/index.md, docs/api/v1.md | README.md |
**/*.{yml,yaml} | config/app.yml | config/app.json |
.mintpress/**/* | .mintpress/properties/bank.json | actions.rb |
A trailing ** matches a single path segment rather than everything beneath it - docs/** matches docs/index.md but not docs/api/v1.md. Write docs/**/* to cover a directory and everything under it.
Negating a pattern
A negated pattern is satisfied by a changed path its glob does not match. It asks for a file outside the glob rather than excluding a commit that touched the glob, so { "match": "docs/**/*", "negate": true } is satisfied by a commit that changed lib/deploy.rb and docs/index.md together, because lib/deploy.rb sits outside docs.
A single negated pattern on its own therefore reads as "run unless the commit touched nothing but the files this glob covers", which is what the example above asks for.
Requiring every pattern to match
commit_file_pattern_match controls how a set of patterns is combined:
any- the default. The change is created as soon as one pattern is satisfied.all- every pattern must be satisfied. Matches accumulate across polls, so a pattern satisfied by an earlier commit stays satisfied while MintPress waits for the rest, and a set of patterns can be met by commits that arrive hours apart. The accumulated matches are cleared once the change is created, ready for the next round.
all with the patterns { "match": "**/*.rb" } and { "match": "config/**/*" } waits until it has seen a commit that changed a Ruby file and a commit that changed something under config. Either one alone leaves the schedule waiting.
Which commits are examined
Each poll examines the commits between the last one the schedule evaluated and the commit the change would run against. Every path those commits added, modified, deleted or renamed is offered to the patterns, including both the old and the new name of a renamed file.
The first poll has no last-evaluated commit, so it walks back to the commit of the most recent change the schedule created. A schedule that has never created a change has nothing to compare against: it creates its first change, then compares from that commit onwards.
Seeing why a change ran
A change created this way records the patterns that were satisfied under the opschain key of its metadata, alongside whatever metadata the schedule carries:
{
"opschain": {
"commit_file_patterns": [{ "match": "**/*.md", "negate": true, "path": "lib/deploy.rb", "sha": "9f2c1d4e8b7a6f5c4d3e2b1a09f8e7d6c5b4a392" }]
}
}
path names a file that satisfied the pattern, and sha the earliest commit in the range that touched it. Both are absent when the patterns were not evaluated against a range of commits - on the schedule's first change, or when MintPress could not read the range.
When the patterns cannot be evaluated
If MintPress cannot work out what changed, it creates the change rather than skipping it, and raises a warning:scheduled_changes:commit_file_patterns event recording why. It does this when more than 1000 commits lie between the two commits, when the repository cannot be read, and when it cannot get exclusive access to the repository within git_remote.fetch_lock_timeout. The event is throttled to one event per hour.
A schedule whose patterns are never satisfied creates no change. If it reaches the end of its schedule that way, it raises the same event type to record that it never ran.
Running a schedule's activities in parallel
By default, a scheduled activity does not start a new change or workflow run while one it created earlier is still waiting or running. It skips that run and raises a warning:scheduled_activity:skipped event, at most once an hour.
To let runs overlap, tick Allow runs to overlap under a repeating schedule in the run dialog, or when editing the scheduled activity. The scheduled activity's header shows Runs can overlap: Yes. From the CLI, use --allow-parallel; through the API, set allow_parallel_execution to true.
The runs only run at the same time where allow_parallel.runs_of_same_change (for a scheduled change) or allow_parallel.runs_of_same_workflow (for a scheduled workflow run) allows it. Both are false by default, so unless you turn the relevant one on, the schedule still creates a run each time, but the runs wait and start one at a time, and the waiting-run limit below applies to them.
A schedule that allows parallel execution still skips a run once five of its runs are waiting to start, for example while they queue for a runner slot. This stops a schedule that fires faster than its runs can start from building an unbounded queue. Runs that are running, finished or paused don't count. Each skip raises the same warning:scheduled_activity:skipped event, at most once an hour, and the event message gives the number of waiting runs. To change the limit, set scheduled_activity_max_waiting_runs.
Setting a schedule
A scheduled change or workflow run runs either Once, on a date and time you pick, or Repeating, on a cron schedule. A one-off schedule is picked from a calendar, a time in your browser's local time zone and a list of suggestions such as Tomorrow, 9:00 am, and is removed once it has run - see scheduling the change. Over the API, it is a scheduled activity created with run_at rather than cron_schedule.
Everywhere MintPress asks for a repeating schedule — the run change and run workflow dialogs, a scheduled activity you are editing, and a cleanup job — the schedule is set the same way. There are three ways to arrive at one, and they all edit the same cron expression, so you can start with one and finish with another.
- Pick a common schedule. The dropdown lists the schedules most often wanted, from every minute up to the first day of the month. Choosing one fills in the rest of the editor.
- Build one. The builder reads as a sentence — every N minutes or hours, or daily, weekly or monthly at a time you choose. A weekly schedule takes any combination of days.
- Write the expression. Choose Expression to type a standard five field cron expression directly: minute, hour, day of month, month, day of week.
Whichever you use, the schedule is described in plain English beneath the editor, so you can confirm it means what you intended before saving.
An expression the builder cannot represent — steps on more than one field, a restriction on the month, or the L and # operators — opens in Expression and leaves the builder unavailable rather than being rewritten into something simpler.
An invalid expression is reported in the form, and on the schedule's header and summary so it is visible without opening the editor. It is refused before it is submitted rather than being sent and rejected by the API.
Changing the schedule of several scheduled activities
To put several scheduled activities on the same schedule, select them in the table and choose Change schedule from Bulk actions. Choose Once and pick a date and time, or Repeating and set a cron schedule, then select Change schedule. Each selected activity switches to the new schedule, whichever kind it ran on before. The repeating schedule starts empty, so the dialog cannot be applied without choosing one.
Each activity is updated separately, and any that cannot be updated is reported in its own notification. Whether a schedule's runs can overlap is left as it was.
Labelling a scheduled activity
Labels let you group scheduled activities, for example by team or release. Add them in the Labels section of the run change or run workflow dialog while Schedule is on, or when editing the scheduled activity, separated by commas. A scheduled activity can have up to 20 labels of at most 100 characters each.
Labels show in the table's Labels column and in the scheduled activity's header. Use the Labels filter, under More, to list the scheduled activities that carry every label you give. Labels belong to the scheduled activity only, and are not copied to the changes and workflow runs it creates. Through the API, set labels and filter with filter[with_label][].
Creating and deleting a scheduled activity
Scheduled changes and workflow runs are created from the Schedule panel of the run dialog: turn on Schedule change (or Schedule workflow), then choose Once or Repeating and set the schedule. For a scheduled change, the same panel holds New commits only and the commit file patterns.
To delete one or more scheduled activities, select the rows you wish to remove using the checkboxes, then choose delete selected from the bulk actions drop down.
Viewing a scheduled activity
Click a row in the scheduled activity table to open that scheduled activity's details page. The header names what the schedule runs and who created it, and summarises when it next runs, whether it repeats, whether its runs can overlap and whether it needs new commits. From the header you can edit the schedule and view the metadata it passes to each activity it creates. The More actions menu holds Disable scheduled activity (Enable scheduled activity while it is disabled) and Delete scheduled activity.
Below the header, the page lists the changes or workflow runs the schedule has created, in the same table as the activity screen.
Editing a scheduled activity
Open a scheduled activity from the table and select the pencil button (Edit schedule). The form uses the same panels as the run change dialog, so everything the schedule carries can be changed in place.
What the schedule runs is a read-only summary — the project, environment, asset, action, Git remote and revision, or the workflow and version for a scheduled workflow run. To run something else, create a new scheduled activity.
Everything else is editable:
| Setting | Scheduled change | Scheduled workflow run |
|---|---|---|
| Schedule - Once or Repeating - Run once and Allow runs to overlap | ✓ | ✓ |
| Property overrides, and the environment variables within them | ✓ | ✓ |
| Notify, metadata and labels | ✓ | ✓ |
| Settings overrides | ✓ | |
| Automatically continue wait steps | ✓ | |
| Input step arguments | ✓ | |
| New commits only and commit file patterns | ✓ | |
| Steps to skip | ✓ |
Steps to skip and input step arguments appear only where the scheduled action resolves to a step tree that has them.
Saving sends every editable value, not only the ones you changed, so an override, a pattern list or a notify target can be emptied as well as amended.
A schedule that could never run is rejected when you save it, and the scheduled activity is left unchanged: a Once time must be in the future, and an end date must not fall before the next run.
Scheduled activities with unexpected data
A scheduled activity created through the API or CLI can hold a value the GUI cannot read. The scheduled activity screens still open: the unreadable fields are shown with defaults, and a notice names each affected scheduled activity and the fields concerned. Check those fields through the API before editing the scheduled activity, because saving the edit form sends the defaults it is showing.