Documentation
¶
Overview ¶
Package gitpolicy provides verification of gittuf-style repository policies. It verifies branch protection rules and signer requirements against a local git repository, reporting which policies are enforced.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BranchProtectionConfig ¶
type BranchProtectionConfig struct {
RequirePR bool `json:"require_pr"`
RequireReviews bool `json:"require_reviews"`
MinReviewers int `json:"min_reviewers,omitempty"`
RequireSignedCommits bool `json:"require_signed_commits"`
EnforceAdmins bool `json:"enforce_admins"`
}
BranchProtectionConfig defines branch protection requirements.
type BranchProtectionStatus ¶
type BranchProtectionStatus struct {
RequirePR bool `json:"require_pr"`
RequireReviews bool `json:"require_reviews"`
MinReviewers int `json:"min_reviewers,omitempty"`
RequireSignedCommits bool `json:"require_signed_commits"`
EnforceAdmins bool `json:"enforce_admins"`
Verified bool `json:"verified"`
// Evidence tracks what was observed in commit history.
MergeCommitCount int `json:"merge_commit_count"`
SignedCommitCount int `json:"signed_commit_count"`
TotalCommitCount int `json:"total_commit_count"`
}
BranchProtectionStatus reports branch protection verification results.
func VerifyBranchProtection ¶
func VerifyBranchProtection(repo *git.Repository, ref string, policy *Policy, maxCommits int) (*BranchProtectionStatus, error)
VerifyBranchProtection checks the commit history on a ref for evidence of branch protection enforcement. It examines merge commit patterns (indicating PR workflow) and cryptographically verifies commit signatures (indicating signing policy).
type Policy ¶
type Policy struct {
Rules []PolicyRuleConfig `json:"rules,omitempty"`
ProtectedBranches map[string]BranchProtectionConfig `json:"protected_branches,omitempty"`
RequiredSigners map[string][]string `json:"required_signers,omitempty"`
// LoadedFrom records which file the policy was loaded from (set during discovery).
LoadedFrom string `json:"-"`
}
Policy represents a parsed gittuf-style policy.
func LoadPolicy ¶
func LoadPolicy(repo *git.Repository, repoPath string) (*Policy, error)
LoadPolicy discovers and loads a gittuf policy from a git repository. It first checks for a gittuf policy ref (refs/gittuf/policy), then falls back to the .gittuf/ directory in the working tree.
func LoadPolicyFromPath ¶
LoadPolicyFromPath loads a policy from an explicit file or directory path.
type PolicyRule ¶
type PolicyRule struct {
Name string `json:"name"`
Description string `json:"description"`
Enforced bool `json:"enforced"`
Details string `json:"details,omitempty"`
}
PolicyRule represents a single policy rule and its enforcement status.
type PolicyRuleConfig ¶
type PolicyRuleConfig struct {
Name string `json:"name"`
Pattern string `json:"pattern"`
AuthorizedKeys []string `json:"authorized_keys,omitempty"`
Threshold int `json:"threshold,omitempty"`
}
PolicyRuleConfig defines a single policy rule from a gittuf policy file.
type SignerPolicyStatus ¶
type SignerPolicyStatus struct {
RequiredSigners []string `json:"required_signers,omitempty"`
VerifiedSigners []string `json:"verified_signers,omitempty"`
MissingSigners []string `json:"missing_signers,omitempty"`
AllSigned bool `json:"all_signed"`
}
SignerPolicyStatus reports signer policy verification results.
func VerifySignerPolicy ¶
func VerifySignerPolicy(repo *git.Repository, ref string, policy *Policy, opts VerifyOptions) (*SignerPolicyStatus, error)
VerifySignerPolicy walks commits on a ref and verifies that commit signers match the required signers defined in the policy.
type VerificationResult ¶
type VerificationResult struct {
Verified bool `json:"verified"`
Ref string `json:"ref"`
PolicyRules []PolicyRule `json:"policy_rules,omitempty"`
BranchProtection *BranchProtectionStatus `json:"branch_protection,omitempty"`
SignerPolicy *SignerPolicyStatus `json:"signer_policy,omitempty"`
ErrorMsg string `json:"error,omitempty"`
Warnings []string `json:"warnings,omitempty"`
}
VerificationResult holds the outcome of policy verification.
func VerifyPolicy ¶
func VerifyPolicy(opts VerifyOptions) (*VerificationResult, error)
VerifyPolicy orchestrates the full policy verification flow. It opens the repository, discovers or loads the policy, and evaluates branch protection and signer requirements.
type VerifyOptions ¶
type VerifyOptions struct {
// RepoPath is the path to the local git repository.
RepoPath string
// TargetRef is the ref to verify policy against (e.g., "refs/heads/main").
TargetRef string
// PolicyPath is an explicit path to a policy file or directory. Optional.
PolicyPath string
// CertIdentity is the expected signer identity for commit signatures.
CertIdentity string
// CertIssuer is the expected OIDC issuer.
CertIssuer string
// MaxCommits limits how many commits to walk for verification.
MaxCommits int
}
VerifyOptions configures policy verification.
Source Files