Scheduled Recurring Tasks

This document describes how Flutter uses GitHub Actions scheduled workflows (cron jobs) to automate the creation and assignment of GitHub issues for recurring maintenance tasks.

Overview

To ensure periodic maintenance responsibilities are completed on schedule without relying on manual tracking, GitHub Actions workflows run on a scheduled timer (on.schedule) to automatically create GitHub issues.

All issues generated by these workflows carry the automated task label, alongside relevant team and domain labels.

Finding Automated Tasks

You can find active or closed automated task issues using the following GitHub issue search queries:

• All open automated tasks (is:issue is:open label:"automated task")
• Localization tasks (is:issue label:"automated task" label:"a: internationalization")

---

Workflow Design Pattern

Scheduled task workflows are placed under .github/workflows/ and use the GitHub CLI (gh issue create) to file issues directly from GitHub Actions jobs.

Standard Template

# Copyright 2014 The Flutter Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

name: Scheduled Task Name

on:
  schedule:
    # Offset cron schedule to avoid high load periods (e.g., top of the hour)
    # Use https://crontab.guru to test and adjust schedules
    - cron: 40 09 2 2,5,8,11 *
  workflow_dispatch:

jobs:
  create_issue:
    name: Create scheduled task issue
    runs-on: ubuntu-latest
    if: ${{ github.repository == 'flutter/flutter' }}
    permissions:
      issues: write
    steps:
      - name: Create scheduled task issue
        run: |
          new_issue_url=$(gh issue create \
            --title "$TITLE" \
            --assignee "$ASSIGNEES" \
            --label "$LABELS" \
            --body "$BODY")
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}
          TITLE: '[Automated Task] Issue Title'
          ASSIGNEES: assignee_username
          LABELS: automated task,team-label
          BODY: |
            ### Task Description

            Detailed context and checklist here.

Key Requirements & Best Practices

1. Permissions: Job permissions must include issues: write.
2. Repository Guard: Include if: ${{ github.repository == 'flutter/flutter' }} to prevent workflows from executing unnecessarily on forks.
3. Manual Trigger: Include workflow_dispatch so workflows can be tested manually.
4. Labels: Every recurring task workflow must apply the automated task label.
5. Offset Cron Schedules:

   The schedule event can be delayed during periods of high loads of GitHub Actions workflow runs. High load times include the start of every hour. If the load is sufficiently high enough, some queued jobs may be dropped. To decrease the chance of delay, schedule your workflow to run at a different time of the hour (e.g., offset minutes like 40 instead of 00).

---

Adding a New Scheduled Task Workflow

To introduce a new automated task:

1. Create a new .yml file in .github/workflows/ following the template above.
2. Define the schedule using standard 5-field cron syntax (test syntax on Crontab Guru). Be sure to offset minutes away from top-of-the-hour (:00) slots.
3. Include clear context and a checklist in the BODY environment variable.
4. Update the Current Active Workflows section in this document.
5. Submit a pull request for review.

For more details on GitHub Action issue creation, see GitHub's Schedule Issue Creation Tutorial.

---

Current Active Workflows

Task Name	Workflow File	Schedule	Description	Labels Applied
Quarterly Localization Update	scheduled-localization-update.yml	Quarterly (40 09 2 2,5,8,11 *)	Prompts team to check for new upstream strings, pull translations from internal console, update flutter_localizations, Material, and Cupertino localizations, run tests, submit PR, and file follow-up issues if stable roll is required.	automated task, a: internationalization, team-framework