Merge remote-tracking branch 'upstream/master' into add-agent-tasks-api

Author: danyalahmed1995

.codecov.yml

@@ -1,7 +1,11 @@
 ignore:
+  # ignore examples
+  - "example"
   # ignore auto-generated code
   - "github/github-accessors.go"
   # ignore experimental scrape package
   - "scrape"
+  # ignore test
+  - "test"
   # ignore tools
   - "tools"

README.md

@@ -20,7 +20,7 @@ go-github will require the N-1 major release of Go by default.
 
 [support-policy]: https://golang.org/doc/devel/release.html#policy
 
-## Development
+## Development ##
 
 If you're interested in using the [GraphQL API v4][], the recommended library is
 [shurcooL/githubv4][].
@@ -66,7 +66,10 @@ Construct a new GitHub client, then use the various services on the client to
 access different parts of the GitHub API. For example:
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 
 // list all organizations for user "willnorris"
 orgs, _, err := client.Organizations.List(context.Background(), "willnorris", nil)
@@ -75,7 +78,10 @@ orgs, _, err := client.Organizations.List(context.Background(), "willnorris", ni
 Some API methods have optional parameters that can be passed. For example:
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 
 // list public repositories for org "github"
 opt := &github.RepositoryListByOrgOptions{Type: "public"}
@@ -95,14 +101,23 @@ For more sample code snippets, head over to the
 
 ### Authentication ###
 
-Use the `WithAuthToken` method to configure your client to authenticate using an
+Use the `github.WithAuthToken` options method to configure your client to authenticate using an
 OAuth token (for example, a [personal access token][]). This is what is needed
 for a majority of use cases aside from GitHub Apps.
 
 ```go
-client := github.NewClient(nil).WithAuthToken("... your access token ...")
+client, err := github.NewClient(github.WithAuthToken("... your access token ..."))
+if err != nil {
+	// Handle error.
+}
 ```
 
+To support more advanced use cases; you can use the `github.WithTransport` option to provide a
+custom `http.RoundTripper` that handles authentication for you, or the `github.WithHTTPClient`
+option to provide a custom `http.Client`. As an example; you can use the `oauth2.Transport`
+from the [golang.org/x/oauth2](https://pkg.go.dev/golang.org/x/oauth2) package to handle OAuth
+token refreshing for you.
+
 Note that when using an authenticated Client, all calls made by the client will
 include the specified OAuth token. Therefore, authenticated clients should
 almost never be shared between different users.
@@ -146,7 +161,10 @@ func main() {
 	}
 
 	// Use installation transport with client.
-	client := github.NewClient(&http.Client{Transport: itr})
+	client, err := github.NewClient(github.WithTransport(itr))
+	if err != nil {
+		// Handle error.
+	}
 
 	// Use client...
 }
@@ -186,11 +204,14 @@ func main() {
 	// InstallationTokenSource has the mechanism to refresh the token when it expires.
 	httpClient := oauth2.NewClient(context.Background(), installationTokenSource)
 
-	client := github.NewClient(httpClient)
+	client, err := github.NewClient(github.WithHTTPClient(httpClient))
+	if err != nil {
+		// Handle error.
+	}
 }
 ```
 
-*Note*: In order to interact with certain APIs, for example writing a file to a repo, one must generate an installation token
+_Note_: In order to interact with certain APIs, for example writing a file to a repo, one must generate an installation token
 using the installation ID of the GitHub app and authenticate with the OAuth method mentioned above. See the examples.
 
 ### Rate Limiting ###
@@ -296,9 +317,10 @@ import (
 	_ "github.com/bartventer/httpcache/store/memcache" //  Register the in-memory backend
 )
 
-client := github.NewClient(
-	httpcache.NewClient("memcache://"),
-).WithAuthToken(os.Getenv("GITHUB_TOKEN"))
+client, err := github.NewClient(github.WithHTTPClient(httpcache.NewClient("memcache://")), github.WithAuthToken(os.Getenv("GITHUB_TOKEN")))
+if err != nil {
+	// Handle error.
+}
 ```
 
 Alternatively, the [bored-engineer/github-conditional-http-transport](https://github.com/bored-engineer/github-conditional-http-transport)
@@ -334,7 +356,10 @@ embedded type of a more specific list options struct (for example
 `github.Response` struct.
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 
 opt := &github.RepositoryListByOrgOptions{
 	ListOptions: github.ListOptions{PerPage: 10},
@@ -372,7 +397,10 @@ To handle rate limiting issues, make sure to use a rate-limiting transport.
 To use these methods, simply create an iterator and then range over it, for example:
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 var allRepos []*github.Repository
 
 // create an iterator and start looping through all the results
@@ -389,7 +417,10 @@ Alternatively, if you wish to use an external package, there is `enrichman/gh-it
 Its iterator will handle pagination for you, looping through all the available results.
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 var allRepos []*github.Repository
 
 // create an iterator and start looping through all the results
@@ -465,12 +496,14 @@ implementing preview features of the GitHub API, we've adopted the following
 versioning policy:
 
 * We increment the **major version** with any incompatible change to
-	non-preview functionality, including changes to the exported Go API surface
-	or behavior of the API.
+  non-preview functionality, including changes to the exported Go API surface
+  or behavior of the API.
+
 * We increment the **minor version** with any backwards-compatible changes to
-	functionality, as well as any changes to preview functionality in the GitHub
-	API. GitHub makes no guarantee about the stability of preview functionality,
-	so neither do we consider it a stable part of the go-github API.
+  functionality, as well as any changes to preview functionality in the GitHub
+  API. GitHub makes no guarantee about the stability of preview functionality,
+  so neither do we consider it a stable part of the go-github API.
+
 * We increment the **patch version** with any backwards-compatible bug fixes.
 
 Preview functionality may take the form of entire methods or simply additional

example/actionpermissions/main.go

@@ -35,7 +35,10 @@ func main() {
 		log.Fatal("No owner: owner of repo must be given")
 	}
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken(token)
+	client, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+		log.Fatal(err)
+	}
 
 	actionsPermissionsRepository, _, err := client.Repositories.GetActionsPermissions(ctx, *owner, *name)
 	if err != nil {

example/auditlogstream/main.go

@@ -157,7 +157,7 @@ func runDelete(args []string) {
 }
 
 func newClient(token, apiURL string) *github.Client {
-	client, err := github.NewClient(nil).WithAuthToken(token).WithEnterpriseURLs(apiURL, apiURL)
+	client, err := github.NewClient(github.WithAuthToken(token), github.WithEnterpriseURLs(apiURL, apiURL))
 	if err != nil {
 		log.Fatalf("Error creating GitHub client: %v", err)
 	}

example/basicauth/main.go

@@ -19,6 +19,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log"
 	"os"
 	"strings"
 
@@ -39,7 +40,10 @@ func main() {
 		Password: strings.TrimSpace(string(password)),
 	}
 
-	client := github.NewClient(tp.Client())
+	client, err := github.NewClient(github.WithHTTPClient(tp.Client()))
+	if err != nil {
+		log.Fatalf("error: %v", err)
+	}
 	ctx := context.Background()
 	user, _, err := client.Users.Get(ctx, "")
 
@@ -52,8 +56,7 @@ func main() {
 	}
 
 	if err != nil {
-		fmt.Printf("\nerror: %v\n", err)
-		return
+		log.Fatalf("error: %v", err)
 	}
 
 	fmt.Printf("\n%v\n", github.Stringify(user))

example/codespaces/newreposecretwithxcrypto/main.go

@@ -73,7 +73,10 @@ func main() {
 	}
 
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken(token)
+	client, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+		log.Fatal(err)
+	}
 
 	if err := addRepoSecret(ctx, client, *owner, *repo, secretName, secretValue); err != nil {
 		log.Fatal(err)

example/codespaces/newusersecretwithxcrypto/main.go

@@ -66,7 +66,10 @@ func main() {
 	}
 
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken(token)
+	client, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+		log.Fatal(err)
+	}
 
 	if err := addUserSecret(ctx, client, secretName, secretValue, *owner, *repo); err != nil {
 		log.Fatal(err)

example/commitpr/main.go

@@ -221,23 +221,27 @@ func main() {
 	if *sourceOwner == "" || *sourceRepo == "" || *commitBranch == "" || *sourceFiles == "" || *authorName == "" || *authorEmail == "" {
 		log.Fatal("You need to specify a non-empty value for the flags `-source-owner`, `-source-repo`, `-commit-branch`, `-files`, `-author-name` and `-author-email`")
 	}
-	client = github.NewClient(nil).WithAuthToken(token)
+	c, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+		log.Fatal(err)
+	}
+	client = c
 
 	ref, err := getRef()
 	if err != nil {
-		log.Fatalf("Unable to get/create the commit reference: %v\n", err)
+		log.Fatalf("Unable to get/create the commit reference: %v", err)
 	}
 	if ref == nil {
 		log.Fatal("No error where returned but the reference is nil")
 	}
 
 	tree, err := getTree(ref)
 	if err != nil {
-		log.Fatalf("Unable to create the tree based on the provided files: %v\n", err)
+		log.Fatalf("Unable to create the tree based on the provided files: %v", err)
 	}
 
 	if err := pushCommit(ref, tree); err != nil {
-		log.Fatalf("Unable to create the commit: %v\n", err)
+		log.Fatalf("Unable to create the commit: %v", err)
 	}
 
 	if err := createPR(); err != nil {

example/contents/main.go

@@ -16,6 +16,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"log"
 	"os"
 	"path/filepath"
 	"strings"
@@ -50,25 +51,25 @@ func main() {
 
 	fmt.Printf("\nDownloading %v/%v/%v at ref %v to %v...\n", owner, repo, repoPath, ref, outputPath)
 
-	client := github.NewClient(nil)
+	client, err := github.NewClient()
+	if err != nil {
+		log.Fatalf("Error creating GitHub client: %v", err)
+	}
 
 	rc, _, err := client.Repositories.DownloadContents(context.Background(), owner, repo, repoPath, &github.RepositoryContentGetOptions{Ref: ref})
 	if err != nil {
-		fmt.Printf("Error: %v\n", err)
-		os.Exit(1)
+		log.Fatalf("Error downloading contents: %v", err)
 	}
 	defer rc.Close()
 
 	f, err := os.Create(outputPath) //#nosec G703 -- path is validated above
 	if err != nil {
-		fmt.Printf("Error: %v\n", err)
-		os.Exit(1)
+		log.Fatalf("Error creating output file: %v", err)
 	}
 	defer f.Close()
 
 	if _, err := io.Copy(f, rc); err != nil {
-		fmt.Printf("Error: %v\n", err)
-		os.Exit(1)
+		log.Fatalf("Error writing to output file: %v", err)
 	}
 
 	fmt.Println("Download completed.")

example/go.mod

@@ -12,8 +12,8 @@ require (
 	github.com/sigstore/sigstore-go v1.1.4
 	go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.43.0
 	go.opentelemetry.io/otel/sdk v1.43.0
-	golang.org/x/crypto v0.50.0
-	golang.org/x/term v0.42.0
+	golang.org/x/crypto v0.51.0
+	golang.org/x/term v0.43.0
 )
 
 require (
@@ -76,11 +76,11 @@ require (
 	go.opentelemetry.io/otel/metric v1.43.0 // indirect
 	go.opentelemetry.io/otel/trace v1.43.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/mod v0.34.0 // indirect
-	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/mod v0.35.0 // indirect
+	golang.org/x/net v0.54.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260316180232-0b37fe3546d5 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260316180232-0b37fe3546d5 // indirect
 	google.golang.org/grpc v1.79.3 // indirect