docs/infra/Scheduled-Recurring-Tasks.md

# 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](https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22automated+task%22) (`is:issue is:open label:"automated task"`)
- [Localization tasks](https://github.com/flutter/flutter/issues?q=is%3Aissue+label%3A%22automated+task%22+label%3A%22a%3A+internationalization%22) (`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

```yaml
# 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](https://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](https://docs.github.com/en/actions/tutorials/manage-your-work/schedule-issue-creation).

---

## Current Active Workflows

| Task Name | Workflow File | Schedule | Description | Labels Applied |
| :--- | :--- | :--- | :--- | :--- |
| **Quarterly Localization Update** | [scheduled-localization-update.yml](../../.github/workflows/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` |