feat: Add ref option to gh cache list

List GitHub Actions caches with `ref` filtering.

> ref string
> The full Git reference for narrowing down the cache. The ref for a branch should be formatted as refs/heads/<branch name>. To reference a pull request use refs/pull/<number>/merge.

ref. https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#list-github-actions-caches-for-a-repository

pkg/cmd/cache/list/list.go

@@ -28,6 +28,7 @@ type ListOptions struct {
 	Order string
 	Sort  string
 	Key   string
+	Ref   string
 }
 
 func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
@@ -51,6 +52,11 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 
 		# List caches that have keys matching a prefix (or that match exactly)
 		$ gh cache list --key key-prefix
+
+		# To list caches for a specific branch, replace <branch-name> with the actual branch name
+		$ gh cache list --ref refs/heads/<branch-name>
+		# To list caches for a specific pull request, replace <pr-number> with the actual pull request number
+		$ gh cache list --ref refs/pull/<pr-number>/merge
 		`),
 		Aliases: []string{"ls"},
 		Args:    cobra.NoArgs,
@@ -74,6 +80,7 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 	cmdutil.StringEnumFlag(cmd, &opts.Order, "order", "O", "desc", []string{"asc", "desc"}, "Order of caches returned")
 	cmdutil.StringEnumFlag(cmd, &opts.Sort, "sort", "S", "last_accessed_at", []string{"created_at", "last_accessed_at", "size_in_bytes"}, "Sort fetched caches")
 	cmd.Flags().StringVarP(&opts.Key, "key", "k", "", "Filter by cache key prefix")
+	cmd.Flags().StringVarP(&opts.Ref, "ref", "r", "", "Filter by ref")
 	cmdutil.AddJSONFlags(cmd, &opts.Exporter, shared.CacheFields)
 
 	return cmd
@@ -92,7 +99,7 @@ func listRun(opts *ListOptions) error {
 	client := api.NewClientFromHTTP(httpClient)
 
 	opts.IO.StartProgressIndicator()
-	result, err := shared.GetCaches(client, repo, shared.GetCachesOptions{Limit: opts.Limit, Sort: opts.Sort, Order: opts.Order, Key: opts.Key})
+	result, err := shared.GetCaches(client, repo, shared.GetCachesOptions{Limit: opts.Limit, Sort: opts.Sort, Order: opts.Order, Key: opts.Key, Ref: opts.Ref})
 	opts.IO.StopProgressIndicator()
 	if err != nil {
 		return fmt.Errorf("%s Failed to get caches: %w", opts.IO.ColorScheme().FailureIcon(), err)

pkg/cmd/cache/list/list_test.go

@@ -31,6 +31,7 @@ func TestNewCmdList(t *testing.T) {
 				Order: "desc",
 				Sort:  "last_accessed_at",
 				Key:   "",
+				Ref:   "",
 			},
 		},
 		{
@@ -41,6 +42,7 @@ func TestNewCmdList(t *testing.T) {
 				Order: "desc",
 				Sort:  "last_accessed_at",
 				Key:   "",
+				Ref:   "",
 			},
 		},
 		{
@@ -56,6 +58,7 @@ func TestNewCmdList(t *testing.T) {
 				Order: "desc",
 				Sort:  "created_at",
 				Key:   "",
+				Ref:   "",
 			},
 		},
 		{
@@ -66,6 +69,7 @@ func TestNewCmdList(t *testing.T) {
 				Order: "asc",
 				Sort:  "last_accessed_at",
 				Key:   "",
+				Ref:   "",
 			},
 		},
 		{
@@ -76,6 +80,18 @@ func TestNewCmdList(t *testing.T) {
 				Order: "desc",
 				Sort:  "last_accessed_at",
 				Key:   "cache-key-prefix-",
+				Ref:   "",
+			},
+		},
+		{
+			name:  "with ref",
+			input: "--ref refs/heads/main",
+			wants: ListOptions{
+				Limit: 30,
+				Order: "desc",
+				Sort:  "last_accessed_at",
+				Key:   "",
+				Ref:   "refs/heads/main",
 			},
 		},
 	}
@@ -206,6 +222,24 @@ ID  KEY  SIZE      CREATED            ACCESSED
 			wantErr:    true,
 			wantErrMsg: "No caches found in OWNER/REPO",
 		},
+		{
+			name: "only requests caches with the provided ref",
+			opts: ListOptions{
+				Ref: "refs/heads/main",
+			},
+			stubs: func(reg *httpmock.Registry) {
+				reg.Register(
+					func(req *http.Request) bool {
+						return req.URL.Query().Get("ref") == "refs/heads/main"
+					},
+					httpmock.JSONResponse(shared.CachePayload{
+						ActionsCaches: []shared.Cache{},
+						TotalCount:    0,
+					}))
+			},
+			wantErr:    true,
+			wantErrMsg: "No caches found in OWNER/REPO",
+		},
 		{
 			name: "displays no results",
 			stubs: func(reg *httpmock.Registry) {

pkg/cmd/cache/shared/shared.go

@@ -40,6 +40,7 @@ type GetCachesOptions struct {
 	Order string
 	Sort  string
 	Key   string
+	Ref   string
 }
 
 // Return a list of caches for a repository. Pass a negative limit to request
@@ -62,6 +63,9 @@ func GetCaches(client *api.Client, repo ghrepo.Interface, opts GetCachesOptions)
 	if opts.Key != "" {
 		path += fmt.Sprintf("&key=%s", url.QueryEscape(opts.Key))
 	}
+	if opts.Ref != "" {
+		path += fmt.Sprintf("&ref=%s", url.QueryEscape(opts.Ref))
+	}
 
 	var result *CachePayload
 pagination: