Documentation
¶
Overview ¶
Package github reads the repository state that workflow files cannot tell us about: which secrets, variables and environments actually exist.
Every lookup here can legitimately fail because the user's token lacks a permission. That is the normal case, not an exception: listing secrets needs admin rights on the repository, which the typical user does not have. So each result carries its own Access status, and a scope that could not be read is reported as UNKNOWN rather than assumed empty. Assuming empty would produce "missing secret" findings for secrets that exist, which is the one mistake the product cannot afford.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Access ¶
type Access int
Access says whether a scope could be read.
const ( // AccessOK means the listing is complete and can be trusted. AccessOK Access = iota // AccessDenied means the token lacks the permission. GitHub answers 403 or, // for organisation scopes, 404. Both mean the same thing to us. AccessDenied // AccessMissing means the scope does not exist, for example an environment // that is referenced by a job but not configured in the repository. AccessMissing // AccessError means the call failed for another reason: network, rate limit, // server error. AccessError // AccessSkipped means the lookup was not attempted, in offline mode or // without a token. AccessSkipped )
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client reads secrets, variables and environments from the GitHub API.
func (*Client) Inventory ¶
Inventory reads every scope Yumlab needs. environments limits the environment lookups to those actually referenced by the workflows.
Inventory does not fail when a scope cannot be read: the failure is recorded in that scope's Access and the rest of the inventory is still collected. It only returns an error when nothing at all could be reached, which means the result would be meaningless.
type Inventory ¶
type Inventory struct {
Owner string
Repo string
RepoSecrets NameSet
RepoVariables NameSet
// OrgSecrets and OrgVariables list the organisation entries that are
// actually granted to this repository, not every entry in the organisation.
// An organisation secret that exists but is not shared with this repository
// is unusable here, so counting it would hide a real problem.
OrgSecrets NameSet
OrgVariables NameSet
// Environments lists the deployment environments configured on the repo.
Environments NameSet
EnvSecrets map[string]NameSet
EnvVariables map[string]NameSet
}
Inventory is everything Yumlab knows about a repository's configured secrets and variables.
func NewInventory ¶
NewInventory returns an inventory with every scope marked as not attempted.
func (*Inventory) EnvironmentSecrets ¶
EnvironmentSecrets returns the secrets of one environment. The zero value is reported as skipped, never as an empty readable set.
func (*Inventory) EnvironmentVariables ¶
EnvironmentVariables returns the variables of one environment.
type NameSet ¶
type NameSet struct {
Access Access
// Reason explains a non-OK access in words the user can act on, typically
// naming the missing permission.
Reason string
// contains filtered or unexported fields
}
NameSet is the set of names in one scope, plus how the listing went.
A NameSet whose Access is not AccessOK is not empty: it is unknown. Callers must check Access before concluding anything from Has.
func NewNameSet ¶
NewNameSet builds a readable set, used by the API client and by the declarative fallback in the config file.
func Unavailable ¶
Unavailable builds a set that could not be read.
func (NameSet) Has ¶
Has reports whether the name is present. It is only meaningful when Access is AccessOK.
type Options ¶
type Options struct {
// Token is the GitHub token. It is required.
Token string
// BaseURL points at a GitHub Enterprise instance. Empty means github.com.
BaseURL string
// Timeout bounds every individual API call.
Timeout time.Duration
}
Options configures the client.
type Repository ¶
type Repository struct {
Owner string
Name string
// Source says where the identification came from, so the user can tell why
// Yumlab is looking at a given repository.
Source string
}
Repository identifies the repository being scanned.
func DetectRepository ¶
func DetectRepository(dir string) (Repository, error)
DetectRepository works out which repository dir belongs to.
In a GitHub Actions run, GITHUB_REPOSITORY is authoritative. Otherwise the origin remote in .git/config is used. Git itself is never invoked, so Yumlab works in containers that ship no git binary.
func ParseSlug ¶
func ParseSlug(s string) (Repository, error)
ParseSlug reads an "owner/name" string.
func (Repository) String ¶
func (r Repository) String() string
Source Files