Skip to main content
A schedule automation starts a run at each time you set. In a run, an agent reads one repository with your instructions and reports what it finds. OuterLayer files an issue for each thing the run reports. A run that finds nothing files nothing. Each issue shows on the Work page as Not started until a member chooses Build on the item’s page. See Build an item that is not started. For example, a run each night can look for tests that fail now and then, and file one issue for each.

What a run can do

A run reads. It does not change anything.
  • It reads one repository. Its token covers only the repository you choose. The token can read the files, the workflow runs and the checks. It has no write permission.
  • It cannot push, open a pull request or write to a tracker. It holds no credential that can write.
  • It gets no build variables and no destinations. See Destinations and secrets.
  • It never starts a build. The agent reads text from the repository, and that text can try to steer the agent. So a member reads each issue first. See Why an issue from outside the team waits.
The agent reports what it found, and OuterLayer files the issues after the run ends. OuterLayer files them only in the repository the run read, or in a Linear team or Jira project of your factory. It removes images from the issue body and writes each mention as plain text.

Before you start

  • You need the Edit factory settings permission.
  • The factory needs a connected GitHub repository. See Connect a repository.
  • The factory needs a self-hosted runner whose builds run in a microVM or a container. See Container builds.
A runner takes a run only when all of these are true:
  • It has sent a heartbeat within three of its own poll intervals. Otherwise OuterLayer counts it as not running.
  • Its builds do not run with shared-user isolation.
  • It is not a managed runner. A managed runner takes no scheduled run.
  • OuterLayer does not provide its sandboxes. A runner whose runner.sandbox.provider setting is "outerlayer" takes no scheduled run.
  • It has a command for a run.
  • Its runner.queues setting includes implement. See the config file.
  • Its repos filter lets the automation’s repository through.
  • It is up to date. See Update a runner.
A runner that meets all of these can still be unavailable for a time. It can be draining, restarting, holding for an update, blocked or low on disk. It takes no run until that state ends. A runner takes builds before it takes runs, so a run can wait while the runner is busy. When no runner can take the runs of the repository you choose, the form and the automation’s page show a warning. The warning names the cause and links to this list. It does not stop you from saving the automation or choosing Run now. If your factory builds on managed runners, the warning also says that a managed runner takes no scheduled run.

Add a schedule automation

  1. Open Settings, then Automations.
  2. Choose New automation, then choose Schedule.
  3. Enter a name.
  4. Under Schedule, choose Hourly, Daily, Weekdays or Weekly. Hourly runs at the start of each hour.
  5. Set the Time, and the Day for Weekly.
  6. Choose the Time zone. The form starts with the time zone of your browser.
  7. Choose the Repository. The run reads its default branch.
  8. In What to look for, tell the agent what to look for. The field holds up to 2,000 characters.
  9. Under File issues in, choose the same repository, or a Linear team or Jira project of the factory.
  10. Set the Daily limit: the most issues the automation files in 24 hours. The default is 5, and you can set 1 to 100.
  11. Choose Save.
The automation is on as soon as you save it. It shows in the Schedules group. Its page shows its settings and the time of the next run. A due time uses the local time of the time zone. A daily run at 09:00 in New York stays at 09:00 New York time when the clocks change. When the last run is still pending or running at a due time, OuterLayer starts no run for that time. The run log shows Skipped.

Start a run now

Choose Run now on the automation’s page. You need the Edit factory settings permission. Run now works while the automation is off. The button is off while the last run is pending or running. It works again after a run fails because no runner took it in 7 days.

How a run files issues

The agent gives each issue a topic: short text that names what the issue is about. OuterLayer uses the topic and the daily limit to hold issues back:
  • One open issue for each topic. While the issue that the automation filed for a topic is open, OuterLayer files no other issue for that topic.
  • A closed topic stays closed. A member can close an issue with no merged pull request linked to it. Then OuterLayer files no new issue for that topic. The same applies when a member chooses Remove from Work on the issue’s item. If a pull request merged before the issue closed, the fix shipped. A later run that finds the topic again files a new issue.
  • The daily limit. The automation files at most its daily limit of issues in 24 hours. At the limit, the agent stops reporting.
  • Secrets. OuterLayer files nothing for an issue whose title, topic or body looks like it holds a secret, such as a token.
OuterLayer remembers each topic for as long as the automation exists. A topic matches an earlier topic only when its text is the same. A topic that the agent words differently is a new topic. The run log names each issue that OuterLayer did not file, and why.

Topics that stay closed

The automation’s page has a section Topics that stay closed. It lists each topic whose issue a member closed without a fix, with a link to that issue. The section is not there when no topic is closed. To let OuterLayer file a topic again, choose File again on its row. You need the Edit factory settings permission. File again files no issue at once. OuterLayer files a new issue the next time a run finds the topic. A run stops after 30 minutes. The run log then shows Failed, and the run files nothing. The agent reads its topics and reports with three CLI commands that only a run’s agent can use. See Run commands.

Read the run log

The automation’s page shows the run log. Each row has the time, who started the run, the result, the cost and a link to the session of the run. OuterLayer keeps each row for 90 days. A pending row gives one of four reasons:
  • No runner of the factory is running. No runner has sent a heartbeat within three of its poll intervals.
  • No running runner takes this automation’s runs. A runner is running, but none meets the conditions in Before you start for this repository.
  • Every runner that takes this run is unavailable. The row names each runner and its state, such as “ollie is low on disk”.
  • The run waits for a free runner. A runner takes builds first, so the run waits until a runner is free.
A run that waits 7 days ends as Failed. OuterLayer then switches the automation off. The row says that no runner took the run in 7 days. It then gives the reason in the past tense, such as “because no runner of the factory was running”. When a tracker refuses an issue, the row shows the tracker’s answer. Sometimes OuterLayer cannot tell whether the tracker created an issue. The row then says where to look, and OuterLayer does not file the issue again.

Notices and the switch-off after repeated failures

OuterLayer tells the creator of a schedule automation when a run waits for a runner or fails. It sends the same notices for other automations that a member adds. See Notices about an automation for who gets them and what each email says. A schedule automation that keeps failing is a waste of runs. So OuterLayer switches it off in either of these cases:
  • Five runs in a row fail.
  • A run waits 7 days and no runner takes it. This ends the run as Failed.
A switched-off automation has no next run. It shows as Switched off in the Inbox, and its page says why and when. OuterLayer sends one email for the switch-off. To turn the automation on again, use the switch on its page. A run then starts at the next due time. To leave the automation off, choose Keep it off on its page. The notice then goes away, and the automation stays off. A save by a member also sets the count of failed runs in a row to zero. OuterLayer never switches off a webhook automation or an automation for issues. To change, switch off or delete a schedule automation, see Change, switch off or delete an automation.