Allow filtering workflow runs by date range in gh run list

[hatsu38]

Describe the feature or problem you'd like to solve

The current gh run list command does not allow filtering workflow runs within a specific date range. While gh run list --created 2024-05-03 works to filter by a single date, it is not possible to search across multiple dates or a date range.
I would like to be able to view a list of jobs within a one-month period using this feature.

Proposed solution

We propose adding options like --from and --to to the gh run list command, which would allow displaying only the workflow runs within the specified date range.

Additional context

I attempted to search for a one-month list of jobs and then calculate the usage time per job for that month, but the lack of date range filtering made this task cumbersome.

[hatsu38]

I may have found a solution.
By doing gh run list --limit 10 --created '2024-04-01T00:00:00..2024-04-30T23:59:59', it seems possible to search within a specified range.

[andyfeller]

@hatsu38 : Thank you for opening up this idea as well as sharing what you learned figuring it out! ❤

As you discovered, gh run list --created calls "List workflow runs for a workflow" endpoint specifying the created field which states:

Returns workflow runs created within the given date-time range. For more information on the syntax, see "Understanding the search syntax."

cli/pkg/cmd/run/shared/shared.go

Lines 333 to 365 in 4896546

	func GetRuns(client *api.Client, repo ghrepo.Interface, opts *FilterOptions, limit int) (*RunsPayload, error) {
	path := fmt.Sprintf("repos/%s/actions/runs", ghrepo.FullName(repo))
	if opts != nil && opts.WorkflowID > 0 {
	path = fmt.Sprintf("repos/%s/actions/workflows/%d/runs", ghrepo.FullName(repo), opts.WorkflowID)
	}
	perPage := limit
	if limit > 100 {
	perPage = 100
	}
	path += fmt.Sprintf("?per_page=%d", perPage)
	path += "&exclude_pull_requests=true" // significantly reduces payload size
	if opts != nil {
	if opts.Branch != "" {
	path += fmt.Sprintf("&branch=%s", url.QueryEscape(opts.Branch))
	}
	if opts.Actor != "" {
	path += fmt.Sprintf("&actor=%s", url.QueryEscape(opts.Actor))
	}
	if opts.Status != "" {
	path += fmt.Sprintf("&status=%s", url.QueryEscape(opts.Status))
	}
	if opts.Event != "" {
	path += fmt.Sprintf("&event=%s", url.QueryEscape(opts.Event))
	}
	if opts.Created != "" {
	path += fmt.Sprintf("&created=%s", url.QueryEscape(opts.Created))
	}
	if opts.Commit != "" {
	path += fmt.Sprintf("&head_sha=%s", url.QueryEscape(opts.Commit))
	}
	}

Suggestion

The gh run list --help documentation could do a better job clarifying --created takes more than a simple date as well as listing some examples:

$ gh run list --help
List recent workflow runs

For more information about output formatting flags, see `gh help formatting`.

USAGE
  gh run list [flags]

ALIASES
  ls

FLAGS
  -b, --branch string     Filter runs by branch
  -c, --commit SHA        Filter runs by the SHA of the commit
      --created date      Filter runs by the date it was created
  -e, --event event       Filter runs by which event triggered the run
  -q, --jq expression     Filter JSON output using a jq expression
      --json fields       Output JSON with the specified fields
  -L, --limit int         Maximum number of runs to fetch (default 20)
  -s, --status string     Filter runs by status: {queued|completed|in_progress|requested|waiting|action_required|cancelled|failure|neutral|skipped|stale|startup_failure|success|timed_out}
  -t, --template string   Format JSON output using a Go template; see "gh help formatting"
  -u, --user string       Filter runs by user who triggered the run
  -w, --workflow string   Filter runs by workflow

INHERITED FLAGS
      --help                     Show help for command
  -R, --repo [HOST/]OWNER/REPO   Select another repository using the [HOST/]OWNER/REPO format

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

More specifically:

      --created date      Filter runs by the date it was created

@hatsu38 : is there anything else you'd suggest for improving the experience?