diff --git a/example/commitpr/main.go b/example/commitpr/main.go index ab30adb7e0a..4df78b485ed 100644 --- a/example/commitpr/main.go +++ b/example/commitpr/main.go @@ -63,7 +63,7 @@ var ctx = context.Background() // getRef returns the commit branch reference object if it exists or creates it // from the base branch before returning it. func getRef() (ref *github.Reference, err error) { - if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, "refs/heads/"+*commitBranch); err == nil { + if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, branchRef(*commitBranch)); err == nil { return ref, nil } @@ -78,14 +78,19 @@ func getRef() (ref *github.Reference, err error) { } var baseRef *github.Reference - if baseRef, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, "refs/heads/"+*baseBranch); err != nil { + if baseRef, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, branchRef(*baseBranch)); err != nil { return nil, err } - newRef := &github.Reference{Ref: github.Ptr("refs/heads/" + *commitBranch), Object: &github.GitObject{SHA: baseRef.Object.SHA}} + newRef := &github.Reference{Ref: github.Ptr(branchRef(*commitBranch)), Object: &github.GitObject{SHA: baseRef.Object.SHA}} ref, _, err = client.Git.CreateRef(ctx, *sourceOwner, *sourceRepo, newRef) return ref, err } +// branchRef generates the fully qualified git reference for the given branch name. +func branchRef(name string) string { + return "refs/heads/" + name +} + // getTree generates the tree to commit based on the given files and the commit // of the ref you got in getRef. func getTree(ref *github.Reference) (tree *github.Tree, err error) { diff --git a/github/checks.go b/github/checks.go index 6f9c4191cda..d39cfa5363b 100644 --- a/github/checks.go +++ b/github/checks.go @@ -269,6 +269,8 @@ type ListCheckRunsResults struct { } // ListCheckRunsForRef lists check runs for a specific ref. +// The ref can be a commit SHA, branch name `heads/`, or tag name `tags/`. +// For more information, see "Git References" in the Git documentation https://git-scm.com/book/en/v2/Git-Internals-Git-References. // // GitHub API docs: https://docs.github.com/rest/checks/runs#list-check-runs-for-a-git-reference // @@ -357,6 +359,8 @@ type ListCheckSuiteResults struct { } // ListCheckSuitesForRef lists check suite for a specific ref. +// The ref can be a commit SHA, branch name `heads/`, or tag name `tags/`. +// For more information, see "Git References" in the Git documentation https://git-scm.com/book/en/v2/Git-Internals-Git-References. // // GitHub API docs: https://docs.github.com/rest/checks/suites#list-check-suites-for-a-git-reference // diff --git a/github/git_refs.go b/github/git_refs.go index 91eb6dd43fa..1f8fb11a4ea 100644 --- a/github/git_refs.go +++ b/github/git_refs.go @@ -14,6 +14,7 @@ import ( // Reference represents a GitHub reference. type Reference struct { + // The name of the fully qualified reference, i.e.: `refs/heads/master`. Ref *string `json:"ref"` URL *string `json:"url"` Object *GitObject `json:"object"` @@ -48,6 +49,7 @@ type updateRefRequest struct { } // GetRef fetches a single reference in a repository. +// The ref must be formatted as `heads/` for branches and `tags/` for tags. // // GitHub API docs: https://docs.github.com/rest/git/refs#get-a-reference // @@ -82,6 +84,7 @@ func refURLEscape(ref string) string { // ReferenceListOptions specifies optional parameters to the // GitService.ListMatchingRefs method. type ReferenceListOptions struct { + // The ref must be formatted as `heads/` for branches and `tags/` for tags. Ref string `url:"-"` ListOptions diff --git a/github/repos_deployments.go b/github/repos_deployments.go index ded36a95b40..ae9978307aa 100644 --- a/github/repos_deployments.go +++ b/github/repos_deployments.go @@ -49,7 +49,7 @@ type DeploymentsListOptions struct { // SHA of the Deployment. SHA string `url:"sha,omitempty"` - // List deployments for a given ref. + // List deployments for a given ref. This can be a branch, tag, or SHA. Ref string `url:"ref,omitempty"` // List deployments for a given task. diff --git a/github/repos_statuses.go b/github/repos_statuses.go index e7b03047521..21f2c4c1e58 100644 --- a/github/repos_statuses.go +++ b/github/repos_statuses.go @@ -43,7 +43,7 @@ func (r RepoStatus) String() string { } // ListStatuses lists the statuses of a repository at the specified -// reference. ref can be a SHA, a branch name, or a tag name. +// reference. The ref can be a SHA, a branch name, or a tag name. // // GitHub API docs: https://docs.github.com/rest/commits/statuses#list-commit-statuses-for-a-reference // @@ -70,7 +70,7 @@ func (s *RepositoriesService) ListStatuses(ctx context.Context, owner, repo, ref } // CreateStatus creates a new status for a repository at the specified -// reference. Ref can be a SHA, a branch name, or a tag name. +// reference. The ref can be a SHA, a branch name, or a tag name. // // GitHub API docs: https://docs.github.com/rest/commits/statuses#create-a-commit-status // @@ -111,7 +111,7 @@ func (s CombinedStatus) String() string { } // GetCombinedStatus returns the combined status of a repository at the specified -// reference. ref can be a SHA, a branch name, or a tag name. +// reference. The ref can be a SHA, a branch name, or a tag name. // // GitHub API docs: https://docs.github.com/rest/commits/statuses#get-the-combined-status-for-a-specific-reference //