maintain-milestones

maintain-milestones

maintain-milestones - Maintain rolling monthly milestones in a target repository

This action keeps monthly milestones aligned to a rolling cadence for a target repository. It manages only milestones titled in YYYY-MM format and ignores any non-monthly titles.

Behavior

• Ensures milestones exist for all months in the current UTC year plus January of next year.
• Closes open monthly milestones from the immediately prior year on or after May (to allow time for performance reviews); milestones from earlier years are closed unconditionally.
• Reopens expected monthly milestones that are closed.
• Sets due dates to the last day of each month at 12:00 UTC to avoid timezone shifts.

Triggers

Use this action in a workflow that you run manually or on a schedule. Common triggers include:

• workflow_dispatch
• schedule

Inputs

Inputs are managed by the action metadata. See the autogenerated table below for details.

Auth and permissions

• Requires permission to read and write milestones (issues: write) in the target repository.
• Authentication options:
  • Set github-token directly.
  • Or set both app-id and app-private-key to mint a GitHub App token.
• If target_repo is omitted, the action defaults to the current repository name.
• If owner is omitted, the action defaults to ${{ github.repository_owner }}.

Planned action types

• close_old: close open YYYY-MM milestones where the year is before the current UTC year. Milestones from the immediately prior year are exempt until May of the current year; milestones from earlier years are always closed.
• create: create missing expected milestones with the computed due date.
• reopen: reopen expected milestones found in closed state.
• set_due_date: update due date when it differs from the expected date.

Output and reporting

Each run writes a summary table including the target repo, current UTC year, dry-run mode, max updates per run, planned action count, and per-milestone actions. The same summary is also written to the job logs.

Notes

This action is idempotent and should converge to zero planned changes after repeated runs. All date calculations are performed in UTC.

Usage

Basic example

maintain-milestones.yml

name: maintain-milestones

on:
  workflow_dispatch:
    inputs:
      target_repo:
        description: "Target repository. Defaults to the current repo."
        required: false
        default: ""
      owner:
        description: "Owner of the repository. Defaults to the current repository owner."
        required: false
        default: ""
      dry_run:
        description: Toggle dry run mode. If true, report changes without applying them.
        type: boolean
        required: false
        default: true
      max_updates_per_run:
        description: Maximum milestone updates/creates/closes/reopens per run
        required: false
        default: "100"

permissions:
  contents: read
  issues: write

jobs:
  maintain-milestones:
    runs-on: ubuntu-latest
    steps:
      - uses: CCBR/actions/maintain-milestones@latest
        with:
          github-token: ${{ secrets.repo_token || '' }}
          owner: ${{ inputs.owner }}
          target_repo: ${{ inputs.target_repo }}
          dry_run: ${{ inputs.dry_run }}
          max_updates_per_run: ${{ inputs.max_updates_per_run }}
          app-id: ${{ vars.CCBR_BOT_APP_ID }}
          app-private-key: ${{ secrets.CCBR_BOT_PRIVATE_KEY }}

Customized inputs

steps:
  - uses: CCBR/actions/maintain-milestones@main
    with:
      github-token: ${{ secrets.repo_token || github.token }}
      owner: CCBR
      target_repo: actions
      dry_run: false
      max_updates_per_run: 50

Inputs

• target_repo: Target repository (excluding the owner). Defaults to the current repo.
• owner: Owner of the repository. Defaults to the current repository owner.
• dry_run: Toggle dry run mode. If true, report changes without applying them. Default: false.
• max_updates_per_run: Maximum milestone updates/creates/closes/reopens per run. Default: 100.
• github-token: GitHub Actions token with access to organization projects. Optional - set the app-id and app-private-key instead.
• app-id: GitHub App ID for authentication. Optional - Use this instead of a token.
• app-private-key: Private key for the GitHub App used for authentication. Optional - Use this instead of a token. Must be set if app-id is set.