gh

Documentation

Overview

Package gh is a thin wrapper around the go-github client that handles authentication for the way we send the PAT to our action images. This package also contains helpful utilities for parsing common event payloads, like pull requests.

Index

• func ListAllPullRequests(ctx context.Context, client *github.Client, org, repo, state string) ([]*github.PullRequest, error)
• func NewClient(ctx context.Context, orgWideAccess bool) (*github.Client, error)
• func NewClientFromApp(ctx context.Context, appID, installationID int64, privateKey []byte) (*github.Client, error)
• func RetrieveSAMLIdentity(ctx context.Context, client *github.Client, orgLogin, userLogin string) (string, error)
• type Create
  • func ParseCreatePayload(payload map[string]interface{}) (*Create, error)
• type OrganizationSAMLIdentity
• type PullRequest
  • func ParsePullRequestPayload(payload map[string]interface{}) (*PullRequest, error)
• type Status
  • func ParseStatusPayload(payload map[string]interface{}) (*Status, error)

Functions

func ListAllPullRequests

func ListAllPullRequests(ctx context.Context, client *github.Client, org, repo, state string) ([]*github.PullRequest, error)

ListAllPullRequests list all pull requests for a given org/repo. State can be one of three values: "open", "closed", or "all".

func NewClient

func NewClient(ctx context.Context, orgWideAccess bool) (*github.Client, error)

NewClient returns a new authenticated GitHub client using the token found at either GITHUB_TOKEN (local repository access) or PAT_OUTREACH_CI (org-wide access).

If your action needs a client for org-wide access you must ensure that the caller of the action (from a GitHub workflow) writes the PAT_OUTREACH_CI secret to the PAT_OUTREACH_CI environment variable. For more information on how to configure an action to make org-wide requests, see the "Configuring an Action to Make Org-Wide GitHub API Requests" section in the README.md of this repository.

func NewClientFromApp

func NewClientFromApp(ctx context.Context, appID, installationID int64, privateKey []byte) (*github.Client, error)

NewClientFromApp uses the github.com/bradleyfalzon/ghinstallation package to create an HTTP transport that utilizes the private key from an app passed in to provide access to the GitHub API. This should rarely ever be used, but is necessary for things like getting SAML identity using GitHub App credentials (an enterprise owner PAT is required otherwise). The GitHub App in this case needs administrative read permissions on the organization, but even with the permissions a normal PAT for the app will not work.

func RetrieveSAMLIdentity

func RetrieveSAMLIdentity(ctx context.Context, client *github.Client, orgLogin, userLogin string) (string, error)

RetrieveSAMLIdentity takes a GitHub client that has been created using the NewClientFromApp function. It uses the HTTP transport on the underlying HTTP client from it to authenticate the request.

Types

type Create

type Create struct {
	Ref        string `json:"ref"`
	RefType    string `json:"ref_type"`
	Repository struct {
		Name  string `json:"name"`
		Owner struct {
			Login string `json:"login"`
		} `json:"owner"`
	} `json:"repository"`
}

Create is a type meant for a create payload to be marshaled into. This type can be extended with fields as they become necessary in actions.

An example of all the fields that could be added to this type can be found in test/payloads/create.json

func ParseCreatePayload

func ParseCreatePayload(payload map[string]interface{}) (*Create, error)

ParseCreatePayload takes a GitHub actions payload and returns a *Create type with the fields from the payload marshaled into the type.

type OrganizationSAMLIdentity

type OrganizationSAMLIdentity struct {
	Organization struct {
		SamlIdentityProvider struct {
			ExternalIdentities struct {
				Nodes []struct {
					SamlIdentity struct {
						NameId string `goql:"keep"` //nolint:revive // Why: NameId is how GitHub represents the field, not NameID.
					} `goql:"keep"`
				} `goql:"keep"`
			} `goql:"externalIdentities(first:$first<Int>,login:$user<String!>)"`
		} `goql:"keep"`
	} `goql:"organization(login:$org<String!>)"`
}

OrganizationSAMLIdentity is the struct type that represents the GraphQL query to get a SAML identity from a specific organization for a specific user.

type PullRequest

type PullRequest struct {
	Title   string `json:"title"`
	Number  int    `json:"number"`
	Commits int    `json:"commits"`
	Head    struct {
		Ref string `json:"ref"` // HEAD branch name
		SHA string `json:"sha"` // SHA of last commit on HEAD
	} `json:"head"`
	Base struct {
		Repo struct {
			Name  string `json:"name"` // Repository name
			Ref   string `json:"ref"`  // Base branch name
			Owner struct {
				Login string `json:"login"` // Owner (organization/user) name
			} `json:"owner"`
		} `json:"repo"`
	} `json:"base"`
}

PullRequest is a type meant for a pull_request payload to be marshaled into. This type can be extended with fields as they become necessary in actions.

An example of all the fields that could be added to this type can be found in test/payloads/pull_request.json

func ParsePullRequestPayload

func ParsePullRequestPayload(payload map[string]interface{}) (*PullRequest, error)

ParsePullRequestPayload takes a GitHub actions payload and returns a *PullRequest type with the fields from the payload marshaled into the type.

type Status

type Status struct {
	State     string  `json:"state"`
	Context   string  `json:"context"`
	TargetURL *string `json:"target_url"`
	Commit    struct {
		SHA     string `json:"SHA"`
		HTMLUrl string `json:"html_url"`
		Author  struct {
			Login   string `json:"login"`
			HTMLUrl string `json:"html_url"`
		} `json:"author"`
	} `json:"commit"`
	Branches []struct {
		Name string `json:"name"`
	} `json:"branches"`
	Repository struct {
		FullName string `json:"full_name"`
		HTMLUrl  string `json:"html_url"`
		Owner    struct {
			Login string `json:"login"`
		} `json:"owner"`
	} `json:"repository"`
}

Status is a type meant for a status payload to be marshaled into. This type can be extended with fields as they become necessary in actions.

An example of all the fields that could be added to this type can be found in test/payloads/status_failure.json and test/payloads/status_success.json.

func ParseStatusPayload

func ParseStatusPayload(payload map[string]interface{}) (*Status, error)

ParseStatusPayload takes a GitHub actions payload and returns a *Status type with the fields from the payload marshaled into the type.