github

Documentation

Overview

Package github provides idempotent helpers for configuring GitHub repositories. Every operation follows a check-then-act pattern so that `apx init --setup-github` can be re-run safely.

All GitHub API calls go through *githubauth.Client — there is no dependency on the gh CLI.

Index

• Variables
• func CIAppName(repo, org string) string
• func CacheAppID(org, appID string) error
• func CacheAppSlug(org, slug string) error
• func CachePEM(org, pemPath string) (string, error)
• func CachePEMFromContents(org, contents string) error
• func CacheUserAppClientID(org, clientID string) error
• func CacheUserAppID(org, appID string) error
• func CacheUserAppSlug(org, slug string) error
• func CheckAppInstalled(client *githubauth.Client, org string, appID int) bool
• func CheckDNSForPages(org, domain string) error
• func ConfigurePagesDomain(client *githubauth.Client, org, repo, domain string, res *SetupResult) error
• func ConfigurePagesVisibility(client *githubauth.Client, org, repo string, res *SetupResult) error
• func EnsureAppInstalled(client *githubauth.Client, org string, appID int, appSlug string) error
• func EnsureBranchProtection(client *githubauth.Client, owner, repo string, res *SetupResult) error
• func EnsureGitHubPages(client *githubauth.Client, org, repo string, res *SetupResult) error
• func EnsureTagProtection(client *githubauth.Client, owner, repo string, res *SetupResult) error
• func GetCachedAppID(org string) string
• func GetCachedAppSlug(org string) string
• func GetCachedUserAppClientID(org string) string
• func GetCachedUserAppID(org string) string
• func GetCachedUserAppSlug(org string) string
• func InstallApp(client *githubauth.Client, org string, appID int, appSlug string) error
• func PEMCachePath(org string) (string, error)
• func SetOrgSecret(client *githubauth.Client, org, name, value, visibility string, ...) error
• func UserAppName(org string) string
• type AppCredentials
  • func CreateAppViaManifest(org, appName string, permissions map[string]string) (*AppCredentials, error)
• type SetupResult
  • func SetupAppRepo(client *githubauth.Client, org, repo string) (*SetupResult, error)
  • func SetupCanonicalRepo(client *githubauth.Client, org, repo, appID, pemPath, siteURL string) (*SetupResult, error)
  • func (r *SetupResult) Add(kind string, name string)
  • func (r *SetupResult) Print()

Variables

var CIAppPermissions = map[string]string{
	"contents":      "write",
	"pull_requests": "write",
	"metadata":      "read",
}

CIAppPermissions returns the permissions for the CI GitHub App.

var ManifestExchangeURL = "https://api.github.com/app-manifests/%s/conversions"

ManifestExchangeURL is the URL template for exchanging a manifest code. Override in tests to point at httptest.Server.

var UserAppPermissions = map[string]string{
	"contents":                    "write",
	"pull_requests":               "write",
	"metadata":                    "read",
	"packages":                    "read",
	"administration":              "write",
	"pages":                       "write",
	"organization_administration": "read",
	"organization_secrets":        "write",
}

UserAppPermissions returns the permissions for the user-facing GitHub App.

Functions

func CIAppName

func CIAppName(repo, org string) string

CIAppName returns the name for the CI app: apx-{repo}-{org}.

func CacheAppID

func CacheAppID(org, appID string) error

CacheAppID writes the CI App ID to ~/.config/apx/<org>-app-id.

func CacheAppSlug

func CacheAppSlug(org, slug string) error

CacheAppSlug writes the CI App slug to ~/.config/apx/<org>-app-slug.

func CachePEM

func CachePEM(org, pemPath string) (string, error)

CachePEM ensures the PEM is cached at ~/.config/apx/<org>-app.pem (0600). If the file already exists it is read and returned. If pemPath is provided and the cache is missing, the file is copied into the cache.

func CachePEMFromContents

func CachePEMFromContents(org, contents string) error

CachePEMFromContents writes PEM contents directly to the cache. Used after the manifest flow returns the PEM as a string.

func CacheUserAppClientID

func CacheUserAppClientID(org, clientID string) error

CacheUserAppClientID writes the user app's client_id.

func CacheUserAppID

func CacheUserAppID(org, appID string) error

CacheUserAppID writes the user app's numeric ID.

func CacheUserAppSlug

func CacheUserAppSlug(org, slug string) error

CacheUserAppSlug writes the user app's slug.

func CheckAppInstalled

func CheckAppInstalled(client *githubauth.Client, org string, appID int) bool

CheckAppInstalled checks whether the GitHub App (by ID) has an installation on the given org.

func CheckDNSForPages

func CheckDNSForPages(org, domain string) error

CheckDNSForPages performs a CNAME lookup on the custom domain and checks that it points to the expected GitHub Pages host ({org}.github.io).

func ConfigurePagesDomain

func ConfigurePagesDomain(client *githubauth.Client, org, repo, domain string, res *SetupResult) error

ConfigurePagesDomain sets a custom domain (CNAME) for GitHub Pages.

func ConfigurePagesVisibility

func ConfigurePagesVisibility(client *githubauth.Client, org, repo string, res *SetupResult) error

ConfigurePagesVisibility sets GitHub Pages visibility to private if the repository is private.

func EnsureAppInstalled

func EnsureAppInstalled(client *githubauth.Client, org string, appID int, appSlug string) error

EnsureAppInstalled verifies the App is installed on the org. If not, it opens the browser to the installation page and polls until done.

func EnsureBranchProtection

func EnsureBranchProtection(client *githubauth.Client, owner, repo string, res *SetupResult) error

EnsureBranchProtection creates or verifies branch protection on main.

func EnsureGitHubPages

func EnsureGitHubPages(client *githubauth.Client, org, repo string, res *SetupResult) error

EnsureGitHubPages enables GitHub Pages with Actions-based deployment. If Pages is already enabled (409 response), it is treated as success.

func EnsureTagProtection

func EnsureTagProtection(client *githubauth.Client, owner, repo string, res *SetupResult) error

EnsureTagProtection creates tag protection rulesets.

func GetCachedAppID

func GetCachedAppID(org string) string

GetCachedAppID returns the cached CI App ID for an org, or "" if not cached.

func GetCachedAppSlug

func GetCachedAppSlug(org string) string

GetCachedAppSlug returns the cached CI App slug for an org, or "" if not cached.

func GetCachedUserAppClientID

func GetCachedUserAppClientID(org string) string

GetCachedUserAppClientID returns the cached user app client_id, or "".

func GetCachedUserAppID

func GetCachedUserAppID(org string) string

GetCachedUserAppID returns the cached user app ID, or "".

func GetCachedUserAppSlug

func GetCachedUserAppSlug(org string) string

GetCachedUserAppSlug returns the cached user app slug, or "".

func InstallApp

func InstallApp(client *githubauth.Client, org string, appID int, appSlug string) error

InstallApp opens the browser to install a GitHub App on an org and polls until the installation is confirmed.

func PEMCachePath

func PEMCachePath(org string) (string, error)

PEMCachePath returns the expected path for the cached PEM for an org.

func SetOrgSecret

func SetOrgSecret(client *githubauth.Client, org, name, value, visibility string, res *SetupResult) error

SetOrgSecret sets (or skips) an org-level Actions secret using the GitHub REST API with NaCl sealed-box encryption.

func UserAppName

func UserAppName(org string) string

UserAppName returns the well-known name for the user app: apx-{org}-user.

Types

type AppCredentials

type AppCredentials struct {
	ID       int    `json:"id"`
	Slug     string `json:"slug"`
	PEM      string `json:"pem"`
	ClientID string `json:"client_id"`
}

AppCredentials holds the result of a GitHub App creation via manifest.

func CreateAppViaManifest

func CreateAppViaManifest(org, appName string, permissions map[string]string) (*AppCredentials, error)

CreateAppViaManifest creates a GitHub App using the manifest flow. It starts a temporary local HTTP server, opens the browser to GitHub's app creation page with a pre-filled manifest, receives the callback code, and exchanges it for the app credentials.

No existing authentication is needed — the manifest code exchange is an unauthenticated endpoint.

type SetupResult

type SetupResult struct {
	Created  []string // things that were created
	Skipped  []string // things that already existed
	Warnings []string // things that need manual action
}

SetupResult tracks what happened during setup so the caller can print a summary.

func SetupAppRepo

func SetupAppRepo(client *githubauth.Client, org, repo string) (*SetupResult, error)

SetupAppRepo runs the idempotent setup for an app repository. It verifies org secrets exist (does not create them) and sets branch protection appropriate for app repos.

func SetupCanonicalRepo

func SetupCanonicalRepo(client *githubauth.Client, org, repo, appID, pemPath, siteURL string) (*SetupResult, error)

SetupCanonicalRepo runs the full idempotent setup sequence for a canonical API repository.

func (*SetupResult) Add

func (r *SetupResult) Add(kind string, name string)

Add appends an entry to the appropriate list.

func (*SetupResult) Print

func (r *SetupResult) Print()

Print outputs a human-readable summary.