feat: add auth_mode for explicit auth configuration by laughedelic · Pull Request #3246 · integrations/terraform-provider-github

laughedelic · 2026-03-02T02:50:52Z

This PR

Resolves [FEAT]: Switching Between PAT and GitHub App Authentication Without Modifying Terraform Code #1877
- Supersedes feat: app-based authentication via env vars without app_auth block #2174
Resolves [MAINT]: Add provider configuration to set auth_mode: 'anonymous' #3117
Partially addresses [MAINT]: Rework provider auth configuration #3116
- see the note at the bottom on why it doesn't resolve that issue
Also, partially addresses Misleading error message when GITHUB_TOKEN not set #598 (improved error when auth_mode is set explicitly)

Before the change?

app_auth {} block is the only way to configure GitHub App authentication; switching between token and app auth requires modifying provider configuration code
When using environment variables for app auth, an empty app_auth {} block is required due to a Terraform SDK limitation ([FEAT]: Switching Between PAT and GitHub App Authentication Without Modifying Terraform Code #1877)
Authentication mode is implicitly auto-detected with no way to opt out: if GITHUB_TOKEN is in the environment or gh CLI has a valid session, anonymous mode is impossible ([MAINT]: Rework provider auth configuration #3116)

After the change?

Based on the proposal in #3116:

New auth_mode argument enables explicit control over authentication:
- auth_mode = "anonymous" ignores any credentials
- auth_mode = "token" errors if no token is provided instead of silently falling back
- auth_mode = "app" errors if app credentials are missing or incomplete
- When auth_mode is not set, the existing auto-detection behavior is preserved (backward compatible)
New top-level app_id, app_installation_id, app_private_key arguments allow app auth without the app_auth block, making it possible to switch between token and app auth purely via environment variables (addressing [FEAT]: Switching Between PAT and GitHub App Authentication Without Modifying Terraform Code #1877)
app_auth block is deprecated with a mention of the new top-level arguments
gh auth token CLI fallback is deprecated (as proposed in [MAINT]: Rework provider auth configuration #3116)

Note, I took the liberty to name the new top-level argument app_private_key instead of app_pem_file because I believe it is more clear that the expected value is a private key content, not a file reference. I remember there was this old comment:

I feel like the naming of the pem_file argument in app_auth is a little confusing because it expects the content of the file, not its path. Maybe calling it private_key would have been clearer

Pull request checklist

Schema migrations have been created if needed (example)
Tests for the changes have been added (for bug fixes / features)
Docs have been reviewed and added / updated if needed (for bug fixes / features)

Does this introduce a breaking change?

No

I didn't implement environment_variable_prefix and auth_type from the #3116's proposal to keep this focused, and implementing those seemed like touching many more places. But I can add those separately.

Follow-up: feat: add env_var_prefix to support multiple providers setup laughedelic/terraform-provider-github#1

github-actions · 2026-03-02T02:51:01Z

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀

github/provider.go

laughedelic · 2026-03-02T03:49:10Z

Thinking some more about the auth_mode and the empty default with some auto-resolution for compatibility: what if it was a priority list instead of a single value? This would allow users to set their own fallback logic by saying auth_mode = ["app", "cli", "token"] and depending on the environment, it would use different options in that order. WDYT?

UPD: Maybe I'm just overcomplicating it. Feel free to ignore this.

deiga

I think this is looking great!

I've been wanting to get to this for a while now 😬

Left a few minor comments

deiga · 2026-03-04T22:24:43Z

github/provider.go

-			var appID, appInstallationID, appPemFile string
+		switch authMode {
+		case "anonymous":
+			log.Printf("[INFO] Auth mode: anonymous")


Could you test if we can use tflog inside this func?

Seems to be fine. Done in e07604b.

deiga · 2026-03-04T22:25:03Z

github/provider.go

+		case "token":
+			token = d.Get("token").(string)
+			if token == "" {
+				return nil, diag.FromErr(fmt.Errorf(


Suggested change

return nil, diag.FromErr(fmt.Errorf(

return nil, diag.Errorf(

Done in c33ccb5

deiga · 2026-03-04T22:27:58Z

github/provider.go

+			"app_id": {
+				Type:        schema.TypeString,
+				Optional:    true,
+				DefaultFunc: schema.EnvDefaultFunc("GITHUB_APP_ID", nil),
+				Description: descriptions["app_id"],
+			},
+			"app_installation_id": {
+				Type:        schema.TypeString,
+				Optional:    true,
+				DefaultFunc: schema.EnvDefaultFunc("GITHUB_APP_INSTALLATION_ID", nil),
+				Description: descriptions["app_installation_id"],
+			},
+			"app_private_key": {
+				Type:        schema.TypeString,
+				Optional:    true,
+				Sensitive:   true,
+				DefaultFunc: schema.EnvDefaultFunc("GITHUB_APP_PRIVATE_KEY", nil),
+				Description: descriptions["app_private_key"],
+			},


Could you add ConflictsWith fields so that it's not possible to set both App auth configs at the same time? Or does that interfere with the DefaultFunc being the same?

I don't think it interferes with the default value, but it probably doesn't raise the conflict when everything is set through env vars. In any case, I added mutually exclusive ConflictsWith in e3264c4. And further validation is done in providerConfigure.

deiga · 2026-03-04T22:32:04Z

github/provider_test.go

+		})
+	})
+
+	t.Run("can be configured with top-level app fields without auth_mode", func(t *testing.T) {


Hmm, I would prefer if this wouldn't be possible. Can we force setting of auth_mode for top-level app fields? Or are we limited by backwards compatibility?

This is a bit more involved than just requiring auth_mode = app if the top-lvel app fields are set. I added an extra validation in the "default" case, to make sure that if the top-level fields are set and there is no app_auth block, we get an error about setting auth_mode.
There are cases when user can set both the token and the app values, but then choose which set of credentials to use via auth_mode. Any or all of them can be set via env vars. So I think this shouldn't be too strict.
See af6fb59. I added some extra tests for the edge cases. Let me know if we're on the same page.

old app_auth

deiga

Whoo! This seems so much simpler than what I had thought it would be 😬

I hope we're not missing something

laughedelic · 2026-03-25T02:25:47Z

@stevehipwell could you give some feedback here?

laughedelic added 6 commits March 2, 2026 02:09

add top-level app creds and a helper function

a6adf15

add explicit auth_mode configuration

4c9ede5

update auth example

06ad80f

add auth_mode tests

7761220

rename app_pem_file to app_private_key

a2010f5

update authentication docs

91625cf

github-actions bot added the Type: Feature New feature or request label Mar 2, 2026

laughedelic commented Mar 2, 2026

View reviewed changes

github/provider.go Show resolved Hide resolved

laughedelic mentioned this pull request Mar 2, 2026

feat: add env_var_prefix to support multiple providers setup laughedelic/terraform-provider-github#1

Draft

3 tasks

deiga suggested changes Mar 4, 2026

View reviewed changes

laughedelic added 4 commits March 5, 2026 03:02

Use tflog in providerConfigure instead of log.Printf

e07604b

Use diag.Errorf instead of diag.FromErr(fmt.Errorf

c33ccb5

Add mutual ConflictsWith between the new top-level parameters and the

e3264c4

old app_auth

Validate auth_mode for top-level app fields and add tests for edge cases

af6fb59

laughedelic requested a review from deiga March 5, 2026 03:14

deiga approved these changes Mar 5, 2026

View reviewed changes

deiga requested a review from stevehipwell March 5, 2026 22:45

Merge branch 'main' into feat/auth-mode-rework

3e17470

	return nil, diag.FromErr(fmt.Errorf(
	return nil, diag.Errorf(

Conversation

laughedelic commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before the change?

After the change?

Pull request checklist

Does this introduce a breaking change?

Uh oh!

github-actions bot commented Mar 2, 2026

Uh oh!

Uh oh!

laughedelic commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

deiga left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deiga left a comment

Choose a reason for hiding this comment

Uh oh!

laughedelic commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

laughedelic commented Mar 2, 2026 •

edited

Loading

laughedelic commented Mar 2, 2026 •

edited

Loading