feat: Add native Go 1.23 Iterator support #3916

merchantmoh-debug · 2026-01-14T14:14:08Z

This PR introduces native Go 1.23 iterator support to the entire library via a new code generator.

The Problem

Pagination in go-github currently requires verbose boilerplate:

opt := &github.RepositoryListByUserOptions{ListOptions: github.ListOptions{PerPage: 10}}
for {
	repos, resp, err := client.Repositories.ListByUser(ctx, "user", opt)
	// handle err
	for _, repo := range repos { ... }
	if resp.NextPage == 0 { break }
	opt.Page = resp.NextPage
}

The Solution: With this PR, users can simply write:

for repo, err := range client.Repositories.ListByUserIter(ctx, "user", opt) {
	if err != nil { log.Fatal(err) }
	fmt.Println(repo.GetName())
}

Implementation Details

github/gen-iterators.go: A new AST-based tool (similar to gen-accessors) that scans all List* methods, identifies their pagination patterns (Page/Cursor), and generates a corresponding *Iter method returning iter.Seq2.
It handles methods using standard ListOptions embedding and explicit Page fields.
It copies the opts struct to avoid mutating the caller's options during iteration.

github/iterators.go: The generated file containing hundreds of type-safe iterators.
Metadata Handling: Updated tools/metadata to exclude the generated iterators from API operation mapping validation, as they wrap existing operations.

Testing & Benchmarks

github/iterators_benchmark_test.go confirms that the iterator abstraction introduces negligible overhead compared to manual looping.

github/iterators_test.go verifies single-page, multi-page, and error handling scenarios.

Tests explicitly verify that the user's opts struct is NOT mutated by the iterator.

Documentation

Added github/example_iterators_test.go to provide a clear example in the Godoc.
This modernizes the library to leverage the latest Go features, significantly improving Developer Experience (DX) by eliminating error-prone pagination boilerplate.

merchantmoh-debug · 2026-01-14T14:15:51Z

@gmlewis - @alexandear

Review when you can guys. Hoping this feature closes the gap between GO and AWS/Azure.

Happy to help :) - Let me know of any changes, hiccups or additions you want. Let's keep the momentum up.

codecov · 2026-01-14T15:08:00Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.51%. Comparing base (6a6a295) to head (9ae96fa).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3916      +/-   ##
==========================================
- Coverage   92.45%   85.51%   -6.95%     
==========================================
  Files         203      204       +1     
  Lines       14980    17554    +2574     
==========================================
+ Hits        13850    15011    +1161     
- Misses        927     1913     +986     
- Partials      203      630     +427

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

gen-iterators

github/gen-iterators.go

github/iterators.go

github/gen-iterators.go

github/github.go

merchantmoh-debug · 2026-01-15T08:10:48Z

@alexandear - @gmlewis = Thanks for the review! I've addressed all the feedback:

Generator Location: Confirmed gen-iterators.go is in the github/ package, matching the pattern of gen-accessors.go.
Go Generate: Added //go:generate go run gen-iterators.go to github/github.go so it runs automatically with other generators.
Test Coverage: The generator now outputs a corresponding iterators_gen_test.go file. This includes a specific test case for every single generated iterator method, ensuring we have 100% coverage of the new functionality.

@Not-Dhananjay-Mishra - Thanks for catching that! It looks like an accidental regression occurred where DependencySBOMCategory (and its RateLimits field) was dropped, likely due to a merge/rebase issue with my local branch.

I have restored the DependencySBOMCategory constant, the GetRateLimitCategory case, and the DependencySBOM field in the RateLimits struct. Tests now pass. I will update the PR shortly.

github/strings.go

gmlewis

Thank you, @merchantmoh-debug - this is looking very promising.

gmlewis · 2026-01-15T14:28:58Z

github/example_iterators_test.go

@@ -0,0 +1,29 @@
+// Copyright 2025 The go-github AUTHORS. All rights reserved.


Yes >.<; good catch.

github/example_iterators_test.go

github/gen-iterators.go

github/iterators_test.go

github/strings.go

.gitignore

gmlewis · 2026-01-15T16:44:14Z

You can completely ignore this suggestion from the email, as it will be taken care of by one of the other suggestions:

-	ctx := context.Background()
-	_ = ctx // avoid unused
-
-	// Call iterator with zero values
-	iter := client.Users.ListUserSocialAccountsIter(context.Background(), "", nil)
+	ctx := context.Background()
+
+	// Call iterator with zero values
+	iter := client.Users.ListUserSocialAccountsIter(ctx, "", nil)

alexandear · 2026-01-15T16:52:22Z

I know it's not ideal to discuss this inside a PR, but we don’t have an issue for this feature, so this is the only place to do it.

Do we really need to generate iterators at all? Maybe we could provide helper functions similar to what we have in the GitLab API client: Scan, Scan2, ScanAndCollect?

The benefits would be:

no need to generate iterators and their tests
less code to maintain

gmlewis · 2026-01-15T17:12:49Z

I know it's not ideal to discuss this inside a PR, but we don’t have an issue for this feature, so this is the only place to do it.

Do we really need to generate iterators at all? Maybe we could provide helper functions similar to what we have in the GitLab API client: Scan, Scan2, ScanAndCollect?

The benefits would be:

no need to generate iterators and their tests

less code to maintain

That is an intriguing suggestion, @alexandear!

There have been many attempts to discuss adding automated pagination to this repo in the past, including:

If you are willing, it might be nice to put together a PR that demonstrates this alternative mechanism and we can compare the two approaches. Would you be willing to work on that, @alexandear?

alexandear · 2026-01-18T18:13:36Z

If you are willing, it might be nice to put together a PR that demonstrates this alternative mechanism and we can compare the two approaches. Would you be willing to work on that, @alexandear?

Working on it in #3925

merchantmoh-debug · 2026-01-23T23:43:27Z

@gmlewis @alexandear - Well; that was a long arse sleep? hahahah. Sorry. My ADHD took me elsewhere and my Autistic hyperfocus kept me there for longer then I wanted.

Mix up reverted. Let's continue shall we?

merchantmoh-debug · 2026-01-24T00:16:58Z

@gmlewis Updates pushed to address all review feedback and build issues:

Build Fix: Patched the generator to explicitly skip ListMatchingRefs, which was causing the undefined: ReferenceListOptions compilation error.
Headers: Regenerated all iterator files with the correct Copyright 2026 and fixed the template to ensure the build tag is the first line.
Cleanup: Reverted accidental changes to strings.go to keep this PR focused solely on the iterator feature.
Verified: Ran the full generator and test suite locally with Go 1.23. All checks pass.
This branch is now fully aligned and conflict-free.

gmlewis

@merchantmoh-debug - this PR has the same issues as your other one.
Please take a look at the GitHub user interface to see all the files included in your PR.

merchantmoh-debug · 2026-01-24T00:27:18Z

@gmlewis - Gotcha

merchantmoh-debug · 2026-01-24T00:35:58Z

@gmlewis - So I reset. Took only the changed files and added them exclusively. Good?

Github interface sucks arse. (Rather I just suck arse and I'm blaming github lmao)

github/gen-iterators.go

gmlewis · 2026-01-24T00:45:35Z

github/gen-iterators.go

+	ctx := context.Background()
+	_ = ctx // avoid unused
+


These 3 lines can still be deleted.

merchantmoh-debug · 2026-01-24T00:48:45Z

@gmlewis Done.

Co-authored-by: Oleksandr Redko <[email protected]>

merchantmoh-debug · 2026-01-28T16:33:26Z

@alexandear @gmlewis - Working on the Otel right now I'll shift back to this in a little while. - suggested commits committed Alex.

Co-authored-by: Oleksandr Redko <[email protected]>

…90030565127

gmlewis

Thank you, @merchantmoh-debug!
LGTM.
I propose that we move forward with this integer-pagination-only mechanism first before tackling cusor-based-pagination in a separate PR.

I would like to hear from our regular reviewers before merging:

alexandear

Should we also update https://github.com/google/go-github#iterators-experimental?

I'm agree that we can limit this PR for the pagination-only iterator.

alexandear · 2026-02-02T10:06:53Z

github/gen-iterators.go

+
+//go:build ignore
+
+// gen-iterators generates iterator methods for List methods.


We should describe more. Especially let's comment about limitations and assumptions.

alexandear · 2026-02-02T10:56:39Z

This PR contains a lot of discussions that would be better placed in an issue.

@merchantmoh-debug, for the future, if you want to add a new major feature, please create an issue first.

github/gen-iterators.go

alexandear · 2026-02-02T11:27:44Z

github/iterators_gen_test.go

This file should be named as the complement to iterators.go: iterators_test.go (not iterators_gen_test.go).

How about github-iterators.go and github-iterators_test.go ?

@gmlewis agree

github/iterators_gen_test.go

alexandear · 2026-02-02T13:33:57Z

@gmlewis could you address all the listed comments instead? To speed up the process.

Co-authored-by: Oleksandr Redko <[email protected]>

gmlewis · 2026-02-02T14:14:51Z

@gmlewis could you address all the listed comments instead? To speed up the process.

Unfortunately, I have to step away from the computer for a few hours, but then if they are not updated, I will attempt to work on these, although I can no longer rename files.

I also want to dig deep and understand what happens during rate limiting during actual iterator usage when I come back.

gmlewis · 2026-02-02T16:44:16Z

OK, I'm back and I believe that rate limiting can all be handled by the transport.

Additionally, I'm thinking of possibly merging this PR and then I would create a follow-on PR to address the remaining issues.
Thoughts, @alexandear, @Not-Dhananjay-Mishra, and @merchantmoh-debug ?

merchantmoh-debug · 2026-02-02T17:12:47Z

@gmlewis - I agree. That's likely the best way to do it. If @alexandear & @Not-Dhananjay-Mishra - I'm onboard.

alexandear · 2026-02-02T17:26:30Z

OK, I'm back and I believe that rate limiting can all be handled by the transport.

Additionally, I'm thinking of possibly merging this PR and then I would create a follow-on PR to address the remaining issues. Thoughts, @alexandear, @Not-Dhananjay-Mishra, and @merchantmoh-debug ?

Looks good. Let's merge.

merchantmoh-debug · 2026-02-02T17:32:38Z

@alexandear - I'm kinda a noob to Codecov --- does it sometimes glitch? Just wondering if satisfying it until it has a green check mark matters -- never dealt with it before

Not-Dhananjay-Mishra · 2026-02-02T17:42:13Z

OK, I'm back and I believe that rate limiting can all be handled by the transport.

Additionally, I'm thinking of possibly merging this PR and then I would create a follow-on PR to address the remaining issues.
Thoughts, @alexandear, @Not-Dhananjay-Mishra, and @merchantmoh-debug ?

Solid, I agree 👍

merchantmoh-debug · 2026-02-02T17:50:13Z

@gmlewis -And we have lift off! Amazing work guys!

gmlewis · 2026-02-02T18:26:35Z

@alexandear - I'm kinda a noob to Codecov --- does it sometimes glitch? Just wondering if satisfying it until it has a green check mark matters -- never dealt with it before

Yes, Codecov seems to be a very delicate thing and I've had quite a history with it.
I use it as a guideline but it is not absolutely required that we get green checkmarks from it before merging...
it is up to the maintainer's discretion.

gmlewis · 2026-02-02T18:28:03Z

Excellent. Thank you, everyone. Merging now and I will post a follow-up PR soon.

merchantmoh-debug · 2026-02-02T18:29:10Z

@gmlewis - Thanks - that's what I read online as well!

2/3rds done. Maybe Google will offer me a job 😂 😂

alexandear suggested changes Jan 14, 2026

View reviewed changes

gen-iterators Outdated Show resolved Hide resolved

alexandear reviewed Jan 14, 2026

View reviewed changes

github/gen-iterators.go Show resolved Hide resolved

github/iterators.go Show resolved Hide resolved

alexandear reviewed Jan 14, 2026

View reviewed changes

github/gen-iterators.go Show resolved Hide resolved

gmlewis added the NeedsReview PR is awaiting a review before merging. label Jan 15, 2026

Not-Dhananjay-Mishra reviewed Jan 15, 2026

View reviewed changes

github/github.go Show resolved Hide resolved

merchantmoh-debug requested a review from alexandear January 15, 2026 08:17

Not-Dhananjay-Mishra reviewed Jan 15, 2026

View reviewed changes

github/strings.go Show resolved Hide resolved

gmlewis requested changes Jan 15, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

merchantmoh-debug requested a review from gmlewis January 23, 2026 23:42

gmlewis requested changes Jan 24, 2026

View reviewed changes

feat: Add native Go 1.23 Iterator support

c73b01c

merchantmoh-debug force-pushed the bolt-sentinel-client-improvement-10999790790030565127 branch from bdb5a29 to c73b01c Compare January 24, 2026 00:29

merchantmoh-debug requested a review from gmlewis January 24, 2026 00:34

gmlewis requested changes Jan 24, 2026

View reviewed changes

fix: remove duplicate comments and unused context in template

313fd90

merchantmoh-debug force-pushed the bolt-sentinel-client-improvement-10999790790030565127 branch from c73b01c to bdb5a29 Compare January 24, 2026 00:48

merchantmoh-debug requested a review from gmlewis January 24, 2026 00:48

Update github/gen-iterators.go

78d5cf1

Co-authored-by: Oleksandr Redko <[email protected]>

Update github/gen-iterators.go

e10b9f5

Co-authored-by: Oleksandr Redko <[email protected]>

merchantmoh-debug force-pushed the bolt-sentinel-client-improvement-10999790790030565127 branch from d4270ad to e10b9f5 Compare January 28, 2026 17:03

Merge branch 'master' into bolt-sentinel-client-improvement-109997907…

86cb830

…90030565127

merchantmoh-debug requested a review from alexandear February 1, 2026 08:14

Merge branch 'master' into bolt-sentinel-client-improvement-109997907…

ccef8d7

…90030565127

gmlewis removed the DO NOT MERGE Do not merge this PR. label Feb 2, 2026

gmlewis approved these changes Feb 2, 2026

View reviewed changes

alexandear reviewed Feb 2, 2026

View reviewed changes

gmlewis mentioned this pull request Feb 2, 2026

Make all "DO NOT EDIT" comments consistent #3959

Closed

Update github/iterators_gen_test.go

9ae96fa

Co-authored-by: Oleksandr Redko <[email protected]>

merchantmoh-debug requested a review from alexandear February 2, 2026 17:30

gmlewis merged commit 91d01f7 into google:master Feb 2, 2026
7 of 8 checks passed

merchantmoh-debug deleted the bolt-sentinel-client-improvement-10999790790030565127 branch February 2, 2026 18:29

gmlewis mentioned this pull request Feb 2, 2026

chore: Address gen-iterators review feedback #3962

Open

gmlewis removed the NeedsReview PR is awaiting a review before merging. label Feb 2, 2026

		@@ -0,0 +1,29 @@
		// Copyright 2025 The go-github AUTHORS. All rights reserved.


		//go:build ignore

		// gen-iterators generates iterator methods for List methods.

feat: Add native Go 1.23 Iterator support #3916

feat: Add native Go 1.23 Iterator support #3916

Conversation

merchantmoh-debug commented Jan 14, 2026 • edited by gmlewis Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The Problem

Implementation Details

Testing & Benchmarks

Documentation

Uh oh!

merchantmoh-debug commented Jan 14, 2026

Uh oh!

codecov bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

merchantmoh-debug commented Jan 15, 2026

Uh oh!

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

gmlewis Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

merchantmoh-debug Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gmlewis commented Jan 15, 2026

Uh oh!

This comment was marked as outdated.

alexandear commented Jan 15, 2026

Uh oh!

gmlewis commented Jan 15, 2026

Uh oh!

alexandear commented Jan 18, 2026

Uh oh!

merchantmoh-debug commented Jan 23, 2026

Uh oh!

merchantmoh-debug commented Jan 24, 2026

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

merchantmoh-debug commented Jan 24, 2026

Uh oh!

merchantmoh-debug commented Jan 24, 2026

Uh oh!

Uh oh!

gmlewis Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

merchantmoh-debug commented Jan 24, 2026

Uh oh!

merchantmoh-debug commented Jan 28, 2026

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

alexandear left a comment

Choose a reason for hiding this comment

Uh oh!

alexandear Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

alexandear commented Feb 2, 2026

merchantmoh-debug commented Jan 14, 2026 •

edited by gmlewis

Loading

codecov bot commented Jan 14, 2026 •

edited

Loading

gmlewis commented Feb 2, 2026 •

edited

Loading