Undocumented behaviour of the -w flag for gh run list

[joshuajtward]

Describe the bug

The -w flag for gh run list behaves differently depending on whether a workflow name or a workflow filename is passed to it. Specifically, if a workflow has been manually disabled then the gh run list -w will only return values with the filename as input, and nothing is returned for the workflow name (assuming no duplicate workflow names...).

Versions checked: 2.44.1, 2.48.0

Steps to reproduce the behavior

1. In a repository with a workflow which has been manually disabled
2. Run gh run list -w my-workflow-name and observe that no runs are found
3. Run gh run list -w my-workflow-name.yml and observe that previous runs are listed (potentially as expected?)

Expected vs actual behavior

Given the nature of workflow naming I can see reasonable grounds for this being a desirable feature of the CLI, so the scope of this issue is just to get the behaviour included in the documentation. If it turns out to be undesirable behaviour then I am happy to raise that as another issue!

Logs

[andyfeller]

Thanks for reporting this issue! ❤ Let's dig into this a little bit and figure out what all can be done. 🙇

How does this code work?

Let's dig into how gh run list works with filenames or workflow names:

cli/pkg/cmd/run/list/list.go

Lines 90 to 122 in 4896546

	func listRun(opts *ListOptions) error {
	baseRepo, err := opts.BaseRepo()
	if err != nil {
	return fmt.Errorf("failed to determine base repo: %w", err)
	}
	c, err := opts.HttpClient()
	if err != nil {
	return fmt.Errorf("failed to create http client: %w", err)
	}
	client := api.NewClientFromHTTP(c)
	filters := &shared.FilterOptions{
	Branch: opts.Branch,
	Actor: opts.Actor,
	Status: opts.Status,
	Event: opts.Event,
	Created: opts.Created,
	Commit: opts.Commit,
	}
	opts.IO.StartProgressIndicator()
	if opts.WorkflowSelector != "" {
	states := []workflowShared.WorkflowState{workflowShared.Active}
	if workflow, err := workflowShared.ResolveWorkflow(
	opts.Prompter, opts.IO, client, baseRepo, false, opts.WorkflowSelector,
	states); err == nil {
	filters.WorkflowID = workflow.ID
	filters.WorkflowName = workflow.Name
	} else {
	return err
	}
	}

I think the salient point in the block above is that gh run list is hardcoded for active state workflows like you said:

cli/pkg/cmd/run/list/list.go

Line 113 in 4896546

states := []workflowShared.WorkflowState{workflowShared.Active}

Switching gears to how gh workflow list -a:

cli/pkg/cmd/workflow/list/list.go

Lines 89 to 97 in 4896546

	if opts.All {
	filteredWorkflows = workflows
	} else {
	for _, workflow := range workflows {
	if !workflow.Disabled() {
	filteredWorkflows = append(filteredWorkflows, workflow)
	}
	}
	}

What to do?

Specifically, if a workflow has been manually disabled then the gh run list -w will only return values with the filename as input, and nothing is returned for the workflow name (assuming no duplicate workflow names...).

Absolutely makes sense, which I think is an easy Option 1. Thinking about how gh workflow list works, I wonder if it also makes sense to add a flag that would allow users to pull inactive workflows as an Option 2.

• Option 1: Update documentation that gh run list -w only works on active workflows
• Option 2: Add flag to gh run list similar to gh workflow list -a

@joshuajtward : what do you think? could you share your use case for retrieving and working with inactive workflows?

[joshuajtward]

Hi @andyfeller! Thanks for the reply, that all makes sense. One thing to add to your Option 1 - gh run list does fetch the disabled workflows, but only if the input is the filename, i.e. you need to add .yml to get the disabled workflows back too. Would it be sufficient to have:

• Option 1: Update documentation to call out the different behaviour when calling gh run list -w with a workflow name vs a filename

This would mean this nuance of the CLI is documented without the need for code changes. Obviously if you prefer adding the -a bring it into line with how gh workflow list works then I'm happy with that approach too for consistency. I'm also happy to raise a PR for either of those options, let me know your thoughts.

In terms of our use cases, we have some pipeline observability tooling which fetches data using gh run list -w. Adding .yml to this solved it for us, but I wanted to document it so fewer people run into this!

[andyfeller]

Just to be clear, I would like to do both: improve documentation and provide the same level of data for those who want it. 👍

Marking this as help wanted for any of our community looking for an low effort issue to pick up.