Documentation
¶
Index ¶
- Constants
- func CheckAuth() error
- func FetchLicence(client *api.RESTClient, id string) (string, error)
- func FetchUsername(client *api.RESTClient) (string, error)
- func IsInstallationToken(client *api.RESTClient) bool
- func ReadLabels(client *api.RESTClient, owner, repo string) ([]model.LabelEntry, error)
- func ReadRepoSettings(client *api.RESTClient, owner, name string) (*model.RepositorySettings, []error, error)
- func RepoContext() (owner string, name string, ok bool)
- func RepoContextAt(dir string) (owner string, name string, ok bool, err error)
- func ResetTokenProbe()
- func SetCurrentRepoFunc(fn func() (repository.Repository, error)) func()
- func SetTokenForHostFunc(fn func(string) (string, string)) func()
- type ApplyResult
- type ErrInsufficientRole
- type ErrInsufficientScope
- type SkippedOperation
Constants ¶
const InstallationTokenReadOp = "read repo settings (installation token)" //nolint:gosec // not a credential
installationTokenUnreliableFields lists repo response fields that GitHub Actions installation tokens (GITHUB_TOKEN / secrets.GITHUB_TOKEN) return as zero values (false / empty string) regardless of the actual repository configuration. Comparing these against the user's config produces false positives ("would set" when the repo is already correct).
The operation name is used as the key in readWarningOperationFields (internal/alter/settings.go) to suppress WouldSet entries for these fields.
Variables ¶
This section is empty.
Functions ¶
func CheckAuth ¶
func CheckAuth() error
CheckAuth verifies that a valid GitHub authentication token is available for github.com. It returns an error if no valid token is available.
func FetchLicence ¶
func FetchLicence(client *api.RESTClient, id string) (string, error)
FetchLicence fetches licence text from the GitHub API. Returns the licence body text as returned by GET /licenses/{id}.
func FetchUsername ¶
func FetchUsername(client *api.RESTClient) (string, error)
FetchUsername returns the authenticated user's login via GET /user. When running in GitHub Actions with an installation token (detected by probing GET /user for a 403), it falls back to GITHUB_REPOSITORY_OWNER.
func IsInstallationToken ¶ added in v0.1.2
func IsInstallationToken(client *api.RESTClient) bool
IsInstallationToken returns true when the token associated with client appears to be a GitHub Actions installation token. Detection works by calling GET /user: installation tokens receive 403, PATs succeed.
Outside GitHub Actions (GITHUB_ACTIONS != "true") this always returns false without making an API call, preserving local-run behaviour.
The result is cached for the lifetime of the process.
func ReadLabels ¶
func ReadLabels(client *api.RESTClient, owner, repo string) ([]model.LabelEntry, error)
ReadLabels fetches all labels from a repository using paginated GET requests. Returns an empty slice (not nil) when the repository has no labels.
func ReadRepoSettings ¶
func ReadRepoSettings(client *api.RESTClient, owner, name string) (*model.RepositorySettings, []error, error)
ReadRepoSettings fetches repository settings from the GitHub API and returns them as a model.RepositorySettings. It makes separate API calls for the standard repository fields and Actions workflow permissions.
The returned warnings slice contains classified access errors (ErrInsufficientScope, ErrInsufficientRole) for sub-calls that returned 403. The corresponding fields in the returned settings are left nil. Callers can log these warnings or ignore them.
func RepoContext ¶
RepoContext detects the GitHub repository for the current directory. It returns the owner and name if a GitHub remote is found. When no remote is configured, it returns ok=false.
func RepoContextAt ¶
RepoContextAt detects the GitHub repository for the given directory. It temporarily changes the working directory to dir before querying git remotes, then restores the original directory. Returns the owner and name if a GitHub remote is found; ok=false otherwise.
func ResetTokenProbe ¶ added in v0.1.2
func ResetTokenProbe()
ResetTokenProbe clears the cached probe result. Intended for tests only.
func SetCurrentRepoFunc ¶
func SetCurrentRepoFunc(fn func() (repository.Repository, error)) func()
SetCurrentRepoFunc replaces the currentRepo function for testing. Returns a restore function that should be called via t.Cleanup.
func SetTokenForHostFunc ¶
SetTokenForHostFunc replaces the tokenForHost function for testing. Returns a restore function that should be called via t.Cleanup.
Types ¶
type ApplyResult ¶
type ApplyResult struct {
Skipped []SkippedOperation
}
ApplyResult collects the outcome of ApplyRepoSettings. Skipped lists operations that failed with access errors and were gracefully skipped.
func ApplyLabels ¶
func ApplyLabels(client *api.RESTClient, owner, repo string, desired, current []model.LabelEntry) (*ApplyResult, error)
ApplyLabels diffs desired labels against current labels and reconciles the difference. Missing labels are created (POST), changed labels are updated (PATCH), and matched labels are skipped. Labels present on GitHub but absent from desired are left untouched (no delete/prune).
Name matching is case-insensitive per GitHub's label behaviour.
Access errors (insufficient scope or role) on individual labels are collected in the returned ApplyResult rather than aborting, so a 403 on one label does not prevent others from being applied.
func ApplyRepoSettings ¶
func ApplyRepoSettings(client *api.RESTClient, owner, name string, settings *model.RepositorySettings) (*ApplyResult, error)
ApplyRepoSettings sends a PATCH /repos/{owner}/{repo} with the declared settings. It also handles fields that require separate API endpoints: topics and Actions workflow permissions. Access errors (insufficient scope or role) are collected in the returned ApplyResult rather than aborting. Hard errors still return as the error value.
type ErrInsufficientRole ¶
type ErrInsufficientRole struct {
StatusCode int
Message string // from JSON body
DocumentURL string // from JSON body
Operation string // e.g. "enable vulnerability alerts"
RequiredRole string // e.g. "admin"
}
ErrInsufficientRole signals the token has sufficient scope but the caller lacks the required repository role (e.g. admin) for the operation.
func (*ErrInsufficientRole) Error ¶
func (e *ErrInsufficientRole) Error() string
type ErrInsufficientScope ¶
type ErrInsufficientScope struct {
StatusCode int
HaveScopes []string // parsed from X-OAuth-Scopes (empty for fine-grained / GITHUB_TOKEN)
NeedScopes []string // parsed from X-Accepted-OAuth-Scopes
Message string // from JSON body
DocumentURL string // from JSON body
Operation string // e.g. "enable vulnerability alerts"
}
ErrInsufficientScope signals the token lacks a required scope or role.
func (*ErrInsufficientScope) Error ¶
func (e *ErrInsufficientScope) Error() string
type SkippedOperation ¶
type SkippedOperation struct {
Operation string // e.g. "set workflow permissions"
Err error // *ErrInsufficientScope or *ErrInsufficientRole
}
SkippedOperation records a sub-operation that was skipped due to insufficient token scope or repository role.
Source Files