go-github/github/actions_cache.go

// Copyright 2022 The go-github AUTHORS. All rights reserved.
//
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package github

import (
	"context"
	"fmt"
)

// ActionsCache represents a GitHub action cache.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#about-the-cache-api
type ActionsCache struct {
	ID             *int64     `json:"id,omitempty" url:"-"`
	Ref            *string    `json:"ref,omitempty" url:"ref"`
	Key            *string    `json:"key,omitempty" url:"key"`
	Version        *string    `json:"version,omitempty" url:"-"`
	LastAccessedAt *Timestamp `json:"last_accessed_at,omitempty" url:"-"`
	CreatedAt      *Timestamp `json:"created_at,omitempty" url:"-"`
	SizeInBytes    *int64     `json:"size_in_bytes,omitempty" url:"-"`
}

// ActionsCacheList represents a list of GitHub actions Cache.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#list-github-actions-caches-for-a-repository
type ActionsCacheList struct {
	TotalCount    int             `json:"total_count"`
	ActionsCaches []*ActionsCache `json:"actions_caches,omitempty"`
}

// ActionsCacheUsage represents a GitHub Actions Cache Usage object.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-usage-for-a-repository
type ActionsCacheUsage struct {
	FullName                string `json:"full_name"`
	ActiveCachesSizeInBytes int64  `json:"active_caches_size_in_bytes"`
	ActiveCachesCount       int    `json:"active_caches_count"`
}

// ActionsCacheUsageList represents a list of repositories with GitHub Actions cache usage for an organization.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-usage-for-a-repository
type ActionsCacheUsageList struct {
	TotalCount     int                  `json:"total_count"`
	RepoCacheUsage []*ActionsCacheUsage `json:"repository_cache_usages,omitempty"`
}

// TotalCacheUsage represents total GitHub actions cache usage of an organization or enterprise.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-usage-for-an-enterprise
type TotalCacheUsage struct {
	TotalActiveCachesUsageSizeInBytes int64 `json:"total_active_caches_size_in_bytes"`
	TotalActiveCachesCount            int   `json:"total_active_caches_count"`
}

// ActionsCacheRetentionLimit represents the GitHub Actions cache retention limit for a repository, organization, or enterprise.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-retention-limit-for-an-organization
type ActionsCacheRetentionLimit struct {
	// MaxCacheRetentionDays is the maximum duration, in days, for which caches
	// in a repository may be retained.
	MaxCacheRetentionDays *int `json:"max_cache_retention_days,omitempty"`
}

// ActionsCacheStorageLimit represents the GitHub Actions cache storage limit for a repository, organization, or enterprise.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-storage-limit-for-an-organization
type ActionsCacheStorageLimit struct {
	// MaxCacheSizeGB is the maximum size limit for the sum of all caches in a
	// repository, in gigabytes.
	MaxCacheSizeGB *int `json:"max_cache_size_gb,omitempty"`
}

// ActionsCacheListOptions represents a list of all possible optional Query parameters for ListCaches method.
//
// GitHub API docs:  https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#list-github-actions-caches-for-a-repository
type ActionsCacheListOptions struct {
	ListOptions
	// The Git reference for the results you want to list.
	// The ref for a branch can be formatted either as refs/heads/<branch name>
	// or simply <branch name>. To reference a pull request use refs/pull/<number>/merge
	Ref *string `url:"ref,omitempty"`
	Key *string `url:"key,omitempty"`
	// Can be one of: "created_at", "last_accessed_at", "size_in_bytes". Default: "last_accessed_at"
	Sort *string `url:"sort,omitempty"`
	// Can be one of: "asc", "desc" Default: desc
	Direction *string `url:"direction,omitempty"`
}

// ListCaches lists the GitHub Actions caches for a repository.
// You must authenticate using an access token with the repo scope to use this endpoint.
//
// Permissions: must have the actions:read permission to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#list-github-actions-caches-for-a-repository
//
//meta:operation GET /repos/{owner}/{repo}/actions/caches
func (s *ActionsService) ListCaches(ctx context.Context, owner, repo string, opts *ActionsCacheListOptions) (*ActionsCacheList, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/caches", owner, repo)
	u, err := addOptions(u, opts)
	if err != nil {
		return nil, nil, err
	}

	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var actionCacheList *ActionsCacheList
	resp, err := s.client.Do(req, &actionCacheList)
	if err != nil {
		return nil, resp, err
	}

	return actionCacheList, resp, nil
}

// DeleteCachesByKey deletes one or more GitHub Actions caches for a repository, using a complete cache key.
// By default, all caches that match the provided key are deleted, but you can optionally provide
// a Git ref to restrict deletions to caches that match both the provided key and the Git ref.
// The ref for a branch can be formatted either as "refs/heads/<branch name>" or simply "<branch name>".
// To reference a pull request use "refs/pull/<number>/merge". If you don't want to use ref just pass nil in parameter.
//
// Permissions: You must authenticate using an access token with the repo scope to use this endpoint. GitHub Apps must have the actions:write permission to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#delete-github-actions-caches-for-a-repository-using-a-cache-key
//
//meta:operation DELETE /repos/{owner}/{repo}/actions/caches
func (s *ActionsService) DeleteCachesByKey(ctx context.Context, owner, repo, key string, ref *string) (*Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/caches", owner, repo)
	u, err := addOptions(u, &ActionsCache{Key: &key, Ref: ref})
	if err != nil {
		return nil, err
	}

	req, err := s.client.NewRequest(ctx, "DELETE", u, nil)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}

// DeleteCachesByID deletes a GitHub Actions cache for a repository, using a cache ID.
//
// Permissions: You must authenticate using an access token with the repo scope to use this endpoint. GitHub Apps must have the actions:write permission to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#delete-a-github-actions-cache-for-a-repository-using-a-cache-id
//
//meta:operation DELETE /repos/{owner}/{repo}/actions/caches/{cache_id}
func (s *ActionsService) DeleteCachesByID(ctx context.Context, owner, repo string, cacheID int64) (*Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/caches/%v", owner, repo, cacheID)
	req, err := s.client.NewRequest(ctx, "DELETE", u, nil)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}

// GetCacheUsageForRepo gets GitHub Actions cache usage for a repository. The data fetched using this API is refreshed approximately every 5 minutes,
// so values returned from this endpoint may take at least 5 minutes to get updated.
//
// Permissions: Anyone with read access to the repository can use this endpoint. If the repository is private, you must use an
// access token with the repo scope. GitHub Apps must have the actions:read permission to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-usage-for-a-repository
//
//meta:operation GET /repos/{owner}/{repo}/actions/cache/usage
func (s *ActionsService) GetCacheUsageForRepo(ctx context.Context, owner, repo string) (*ActionsCacheUsage, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/cache/usage", owner, repo)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var cacheUsage *ActionsCacheUsage
	res, err := s.client.Do(req, &cacheUsage)
	if err != nil {
		return nil, res, err
	}

	return cacheUsage, res, err
}

// ListCacheUsageByRepoForOrg lists repositories and their GitHub Actions cache usage for an organization. The data fetched using this API is
// refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.
//
// Permissions: You must authenticate using an access token with the read:org scope to use this endpoint.
// GitHub Apps must have the organization_administration:read permission to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#list-repositories-with-github-actions-cache-usage-for-an-organization
//
//meta:operation GET /orgs/{org}/actions/cache/usage-by-repository
func (s *ActionsService) ListCacheUsageByRepoForOrg(ctx context.Context, org string, opts *ListOptions) (*ActionsCacheUsageList, *Response, error) {
	u := fmt.Sprintf("orgs/%v/actions/cache/usage-by-repository", org)
	u, err := addOptions(u, opts)
	if err != nil {
		return nil, nil, err
	}

	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var cacheUsage *ActionsCacheUsageList
	res, err := s.client.Do(req, &cacheUsage)
	if err != nil {
		return nil, res, err
	}

	return cacheUsage, res, err
}

// GetTotalCacheUsageForOrg gets the total GitHub Actions cache usage for an organization. The data fetched using this API is refreshed approximately every
// 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.
//
// Permissions: You must authenticate using an access token with the read:org scope to use this endpoint.
// GitHub Apps must have the organization_administration:read permission to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-usage-for-an-organization
//
//meta:operation GET /orgs/{org}/actions/cache/usage
func (s *ActionsService) GetTotalCacheUsageForOrg(ctx context.Context, org string) (*TotalCacheUsage, *Response, error) {
	u := fmt.Sprintf("orgs/%v/actions/cache/usage", org)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var cacheUsage *TotalCacheUsage
	res, err := s.client.Do(req, &cacheUsage)
	if err != nil {
		return nil, res, err
	}

	return cacheUsage, res, err
}

// GetTotalCacheUsageForEnterprise gets the total GitHub Actions cache usage for an enterprise. The data fetched using this API is refreshed approximately every 5 minutes,
// so values returned from this endpoint may take at least 5 minutes to get updated.
//
// Permissions: You must authenticate using an access token with the "admin:enterprise" scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-usage-for-an-enterprise
//
//meta:operation GET /enterprises/{enterprise}/actions/cache/usage
func (s *ActionsService) GetTotalCacheUsageForEnterprise(ctx context.Context, enterprise string) (*TotalCacheUsage, *Response, error) {
	u := fmt.Sprintf("enterprises/%v/actions/cache/usage", enterprise)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var cacheUsage *TotalCacheUsage
	res, err := s.client.Do(req, &cacheUsage)
	if err != nil {
		return nil, res, err
	}

	return cacheUsage, res, err
}

// GetCacheRetentionLimitForOrg gets the GitHub Actions cache retention limit for an organization.
// Repositories in the organization may not set a higher cache retention limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:organization scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-retention-limit-for-an-organization
//
//meta:operation GET /organizations/{org}/actions/cache/retention-limit
func (s *ActionsService) GetCacheRetentionLimitForOrg(ctx context.Context, org string) (*ActionsCacheRetentionLimit, *Response, error) {
	u := fmt.Sprintf("organizations/%v/actions/cache/retention-limit", org)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var limit *ActionsCacheRetentionLimit
	res, err := s.client.Do(req, &limit)
	if err != nil {
		return nil, res, err
	}

	return limit, res, nil
}

// SetCacheRetentionLimitForOrg sets the GitHub Actions cache retention limit for an organization.
// Repositories in the organization may not set a higher cache retention limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:organization scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#set-github-actions-cache-retention-limit-for-an-organization
//
//meta:operation PUT /organizations/{org}/actions/cache/retention-limit
func (s *ActionsService) SetCacheRetentionLimitForOrg(ctx context.Context, org string, body ActionsCacheRetentionLimit) (*Response, error) {
	u := fmt.Sprintf("organizations/%v/actions/cache/retention-limit", org)
	req, err := s.client.NewRequest(ctx, "PUT", u, body)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}

// GetCacheStorageLimitForOrg gets the GitHub Actions cache storage limit for an organization.
// Repositories in the organization may not set a higher cache storage limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:organization scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-storage-limit-for-an-organization
//
//meta:operation GET /organizations/{org}/actions/cache/storage-limit
func (s *ActionsService) GetCacheStorageLimitForOrg(ctx context.Context, org string) (*ActionsCacheStorageLimit, *Response, error) {
	u := fmt.Sprintf("organizations/%v/actions/cache/storage-limit", org)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var limit *ActionsCacheStorageLimit
	res, err := s.client.Do(req, &limit)
	if err != nil {
		return nil, res, err
	}

	return limit, res, nil
}

// SetCacheStorageLimitForOrg sets the GitHub Actions cache storage limit for an organization.
// Repositories in the organization may not set a higher cache storage limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:organization scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#set-github-actions-cache-storage-limit-for-an-organization
//
//meta:operation PUT /organizations/{org}/actions/cache/storage-limit
func (s *ActionsService) SetCacheStorageLimitForOrg(ctx context.Context, org string, body ActionsCacheStorageLimit) (*Response, error) {
	u := fmt.Sprintf("organizations/%v/actions/cache/storage-limit", org)
	req, err := s.client.NewRequest(ctx, "PUT", u, body)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}

// GetCacheRetentionLimitForRepo gets the GitHub Actions cache retention limit for a repository.
// This determines how long caches will be retained for, if not manually removed or evicted due to size constraints.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:repository scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-retention-limit-for-a-repository
//
//meta:operation GET /repos/{owner}/{repo}/actions/cache/retention-limit
func (s *ActionsService) GetCacheRetentionLimitForRepo(ctx context.Context, owner, repo string) (*ActionsCacheRetentionLimit, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/cache/retention-limit", owner, repo)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var limit *ActionsCacheRetentionLimit
	res, err := s.client.Do(req, &limit)
	if err != nil {
		return nil, res, err
	}

	return limit, res, nil
}

// SetCacheRetentionLimitForRepo sets the GitHub Actions cache retention limit for a repository.
// This determines how long caches will be retained for, if not manually removed or evicted due to size constraints.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:repository scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#set-github-actions-cache-retention-limit-for-a-repository
//
//meta:operation PUT /repos/{owner}/{repo}/actions/cache/retention-limit
func (s *ActionsService) SetCacheRetentionLimitForRepo(ctx context.Context, owner, repo string, body ActionsCacheRetentionLimit) (*Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/cache/retention-limit", owner, repo)
	req, err := s.client.NewRequest(ctx, "PUT", u, body)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}

// GetCacheStorageLimitForRepo gets the GitHub Actions cache storage limit for a repository.
// This determines the maximum size of caches that can be stored before eviction occurs.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:repository scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-storage-limit-for-a-repository
//
//meta:operation GET /repos/{owner}/{repo}/actions/cache/storage-limit
func (s *ActionsService) GetCacheStorageLimitForRepo(ctx context.Context, owner, repo string) (*ActionsCacheStorageLimit, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/cache/storage-limit", owner, repo)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var limit *ActionsCacheStorageLimit
	res, err := s.client.Do(req, &limit)
	if err != nil {
		return nil, res, err
	}

	return limit, res, nil
}

// SetCacheStorageLimitForRepo sets the GitHub Actions cache storage limit for a repository.
// This determines the maximum size of caches that can be stored before eviction occurs.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:repository scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#set-github-actions-cache-storage-limit-for-a-repository
//
//meta:operation PUT /repos/{owner}/{repo}/actions/cache/storage-limit
func (s *ActionsService) SetCacheStorageLimitForRepo(ctx context.Context, owner, repo string, body ActionsCacheStorageLimit) (*Response, error) {
	u := fmt.Sprintf("repos/%v/%v/actions/cache/storage-limit", owner, repo)
	req, err := s.client.NewRequest(ctx, "PUT", u, body)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}

// GetCacheRetentionLimitForEnterprise gets the GitHub Actions cache retention limit for an enterprise.
// Organizations and repositories in the enterprise may not set a higher cache retention limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-retention-limit-for-an-enterprise
//
//meta:operation GET /enterprises/{enterprise}/actions/cache/retention-limit
func (s *ActionsService) GetCacheRetentionLimitForEnterprise(ctx context.Context, enterprise string) (*ActionsCacheRetentionLimit, *Response, error) {
	u := fmt.Sprintf("enterprises/%v/actions/cache/retention-limit", enterprise)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var limit *ActionsCacheRetentionLimit
	res, err := s.client.Do(req, &limit)
	if err != nil {
		return nil, res, err
	}

	return limit, res, nil
}

// SetCacheRetentionLimitForEnterprise sets the GitHub Actions cache retention limit for an enterprise.
// Organizations and repositories in the enterprise may not set a higher cache retention limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#set-github-actions-cache-retention-limit-for-an-enterprise
//
//meta:operation PUT /enterprises/{enterprise}/actions/cache/retention-limit
func (s *ActionsService) SetCacheRetentionLimitForEnterprise(ctx context.Context, enterprise string, body ActionsCacheRetentionLimit) (*Response, error) {
	u := fmt.Sprintf("enterprises/%v/actions/cache/retention-limit", enterprise)
	req, err := s.client.NewRequest(ctx, "PUT", u, body)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}

// GetCacheStorageLimitForEnterprise gets the GitHub Actions cache storage limit for an enterprise.
// Organizations and repositories in the enterprise may not set a higher cache storage limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#get-github-actions-cache-storage-limit-for-an-enterprise
//
//meta:operation GET /enterprises/{enterprise}/actions/cache/storage-limit
func (s *ActionsService) GetCacheStorageLimitForEnterprise(ctx context.Context, enterprise string) (*ActionsCacheStorageLimit, *Response, error) {
	u := fmt.Sprintf("enterprises/%v/actions/cache/storage-limit", enterprise)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var limit *ActionsCacheStorageLimit
	res, err := s.client.Do(req, &limit)
	if err != nil {
		return nil, res, err
	}

	return limit, res, nil
}

// SetCacheStorageLimitForEnterprise sets the GitHub Actions cache storage limit for an enterprise.
// Organizations and repositories in the enterprise may not set a higher cache storage limit.
//
// Permissions: OAuth tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.
//
// GitHub API docs: https://docs.github.com/rest/actions/cache?apiVersion=2022-11-28#set-github-actions-cache-storage-limit-for-an-enterprise
//
//meta:operation PUT /enterprises/{enterprise}/actions/cache/storage-limit
func (s *ActionsService) SetCacheStorageLimitForEnterprise(ctx context.Context, enterprise string, body ActionsCacheStorageLimit) (*Response, error) {
	u := fmt.Sprintf("enterprises/%v/actions/cache/storage-limit", enterprise)
	req, err := s.client.NewRequest(ctx, "PUT", u, body)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}