feat: GitHub Search

README.md

@@ -426,6 +426,24 @@ echo "gruntwork-io/terragrunt gruntwork-io/terratest" | git-xargs \
   "$(pwd)/scripts/update-copyright-year.sh"
 ```
 
+### Option #5: Select repos via the GitHub Search API
+
+The repository scope can be narrowed down by using the GitHub Search API. This allows you to select repositories based on various criteria, such as language, topics, or other metadata or file content.
+
+- `--github-repository-search` to select repositories based on the [GitHub Repository Search API](https://docs.github.com/en/search-github/searching-on-github/searching-for-repositories)
+- `--github-code-search` to select repositories based on the [GitHub Code Search API](https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax)
+- `--github-org` still can be used, it will add `org:<name>` to the search query
+
+If both, `--github-repository-search` and `--github-code-search` are provided, the repositories will be filtered by both criteria.
+
+```
+git-xargs \
+  --github-org <your-github-org> \
+  --github-repository-search "is:private language:go" \
+  --github-code-search "filename:Dockerfile ubuntu" \
+  "$(pwd)/scripts/update-copyright-year.sh"
+```
+
 ## Notable flags
 
 `git-xargs` exposes several flags that allow you to customize its behavior to better suit your needs. For the latest info on flags, you should run `git-xargs --help`. However, a couple of the flags are worth explaining more in depth here:

auth/auth.go

@@ -24,6 +24,12 @@ type githubRepositoriesService interface {
 	ListByOrg(ctx context.Context, org string, opts *github.RepositoryListByOrgOptions) ([]*github.Repository, *github.Response, error)
 }
 
+// The go-github package satisfies this Search service's interface in production
+type githubSearchService interface {
+	Repositories(ctx context.Context, query string, opts *github.SearchOptions) (*github.RepositoriesSearchResult, *github.Response, error)
+	Code(ctx context.Context, query string, opts *github.SearchOptions) (*github.CodeSearchResult, *github.Response, error)
+}
+
 // GithubClient is the data structure that is common between production code and test code. In production code,
 // go-github satisfies the PullRequests and Repositories service interfaces, whereas in test the concrete
 // implementations for these same services are mocks that return a static slice of pointers to GitHub repositories,
@@ -32,12 +38,14 @@ type githubRepositoriesService interface {
 type GithubClient struct {
 	PullRequests githubPullRequestService
 	Repositories githubRepositoriesService
+	Search       githubSearchService
 }
 
 func NewClient(client *github.Client) GithubClient {
 	return GithubClient{
 		PullRequests: client.PullRequests,
 		Repositories: client.Repositories,
+		Search:       client.Search,
 	}
 }
 

cmd/git-xargs.go

@@ -36,6 +36,8 @@ func parseGitXargsConfig(c *cli.Context) (*config.GitXargsConfig, error) {
 	config.TeamReviewers = c.StringSlice("team-reviewers")
 	config.ReposFile = c.String("repos")
 	config.GithubOrg = c.String("github-org")
+	config.GithubRepositorySearch = c.String("github-repository-search")
+	config.GithubCodeSearch = c.String("github-code-search")
 	config.RepoSlice = c.StringSlice("repo")
 	config.MaxConcurrentRepos = c.Int("max-concurrent-repos")
 	config.SecondsToSleepBetweenPRs = c.Int("seconds-between-prs")

common/common.go

@@ -30,6 +30,8 @@ const (
 	DefaultSecondsBetweenPRs             = 1
 	DefaultMaxPullRequestRetries         = 3
 	DefaultSecondsToWaitWhenRateLimited  = 60
+	GithubRepositorySearchFlagName       = "github-repository-search"
+	GithubCodeSearchFlagName             = "github-code-search"
 )
 
 var (
@@ -120,4 +122,12 @@ var (
 		Name:  KeepClonedRepositoriesFlagName,
 		Usage: "By default, git-xargs deletes the cloned repositories from the temp directory after the command has finished running, to save space on your machine. Pass this flag to prevent git-xargs from deleting the cloned repositories.",
 	}
+	GenericGithubRepositorySearchFlag = cli.StringFlag{
+		Name:  GithubRepositorySearchFlagName,
+		Usage: "GitHub repository search query to find repositories (e.g., 'language:go', 'is:private', 'topic:docker'). See GitHub repository search syntax for more options.",
+	}
+	GenericGithubCodeSearchFlag = cli.StringFlag{
+		Name:  GithubCodeSearchFlagName,
+		Usage: "GitHub code search query to find repositories containing matching code (e.g., 'path:Dockerfile', 'filename:package.json', 'extension:py print'). Repositories will be extracted from code search results. See GitHub code search syntax for more options.",
+	}
 )

config/config.go

@@ -28,6 +28,8 @@ type GitXargsConfig struct {
 	TeamReviewers                 []string
 	ReposFile                     string
 	GithubOrg                     string
+	GithubRepositorySearch        string
+	GithubCodeSearch              string
 	RepoSlice                     []string
 	RepoFromStdIn                 []string
 	Args                          []string
@@ -61,6 +63,8 @@ func NewGitXargsConfig() *GitXargsConfig {
 		TeamReviewers:                 []string{},
 		ReposFile:                     "",
 		GithubOrg:                     "",
+		GithubRepositorySearch:        "",
+		GithubCodeSearch:              "",
 		RepoSlice:                     []string{},
 		RepoFromStdIn:                 []string{},
 		Args:                          []string{},

io/validate-input.go

@@ -8,7 +8,8 @@ import (
 
 // EnsureValidOptionsPassed checks that user has provided one valid method for selecting repos to operate on
 func EnsureValidOptionsPassed(config *config.GitXargsConfig) error {
-	if len(config.RepoSlice) < 1 && config.ReposFile == "" && config.GithubOrg == "" && len(config.RepoFromStdIn) == 0 {
+	if len(config.RepoSlice) < 1 && config.ReposFile == "" && config.GithubOrg == "" &&
+		config.GithubRepositorySearch == "" && config.GithubCodeSearch == "" && len(config.RepoFromStdIn) == 0 {
 		return errors.WithStackTrace(types.NoRepoSelectionsMadeErr{})
 	}
 	if config.BranchName == "" {

main.go

@@ -79,6 +79,8 @@ func setupApp() *cli.App {
 		common.GenericMaxConcurrentClonesFlag,
 		common.GenericNoSkipCIFlag,
 		common.GenericKeepClonedRepositoriesFlag,
+		common.GenericGithubRepositorySearchFlag,
+		common.GenericGithubCodeSearchFlag,
 	}
 
 	app.Action = cmd.RunGitXargs