Fix: Add useHttpPath to support multiple Git credentials on same host

[ab-ghosh]

Changes

This PR fixes a bug where multiple Git repositories on the same host could not use different credentials. When users linked multiple secrets to a ServiceAccount for different repositories on the same Git server (e.g., github.com/org/repo1 and github.com/org/repo2), it would incorrectly use the first credential for all repositories, causing authentication failures. The root cause was that Git's credential helper only matched by hostname, ignoring the repository path. This fix adds useHttpPath = true to Git credential contexts when the annotation URL includes a path, instructing Git to match credentials based on the full repository URL. Additionally, credentials are now automatically sorted in .git-credentials so that host-only credentials come first (serving as fallbacks) and repo-specific credentials come last, ensuring proper fallback behavior regardless of the order secrets are listed in the ServiceAccount. The solution is backwards compatible, requires no configuration changes, and includes comprehensive test coverage including new tests for multiple repo-specific credentials and mixed credential scenarios.

• pkg/credentials/gitcreds/basic.go: Added useHttpPath=true to configBlurb()
• pkg/credentials/gitcreds/creds_test.go: Added TestBasicFlagHandlingMultipleReposSameHost and TestBasicFlagHandlingMixedCredentials
• docs/auth.md: Added documentation for multiple credentials on same host with examples

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has Docs if any changes are user facing, including updates to minimum requirements e.g. Kubernetes version bumps
• Has Tests included if any functionality added or changed
• pre-commit Passed
• Follows the commit message standard
• Meets the Tekton contributor standards (including functionality, content, code)
• Has a kind label. You can add one by adding a comment on this PR that contains /kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tep
• Release notes block below has been updated with any user facing changes (API changes, bug fixes, changes requiring upgrade notices or deprecation warnings). See some examples of good release notes.
• Release notes contains the string "action required" if the change requires additional action from users switching to the new release

Release Notes

Fixed Git credential matching to support multiple repositories on the same host with different credentials. Previously, when using multiple secrets for different repositories on the same Git server (e.g., github.com/org/repo1 and github.com/org/repo2), it incorrectly use the first credential for all repositories, causing authentication failures. Git credential contexts now include `useHttpPath = true`, enabling proper per-repository credential selection.

[tekton-robot]

@ab-ghosh: The label(s) kind/fix cannot be applied, because the repository doesn't have them.

Details

In response to this:

/kind fix

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[ab-ghosh]

/kind bug

[ab-ghosh]

cc @vdemeester @waveywaves

[aThorp96]

Thanks @ab-ghosh! The useHttpPath setting seems like an elegant fix, I like it. I think we need to consider further when it's used, but in general I like it. See my comment for details on the issue with using it in every case

[aThorp96]

This works in the case where each repository has different secrets, but this would break the existing behavior if one secret is authorized on multiple repositories.

For example if I have the following gitconfig with , the credential will not be used if I'm cloning https://gitea.com/test/repo2.

# ~/.gitconfig
[credential]
 	helper = store

# password in ~/.git-credentials
[credential "https://gitea.com/test/repo1"]
 	username = user1
 	useHttpPath = true

We should only set useHttpPath = true when the basicEntry shares a hostname with other basicEntrys in the basicGitConfig. Something like this should work okay to ensure that when a credential entry references the same host as another entry both entries will have useHttpPath = true, but otherwise all credential entries would omit the useHttpPath setting entirely

	multiRepoHosts := []string{}

	seenHosts := []string{}
	for k, v := range dc.entries {
		if slices.Contains(seenHosts, v.authURL.Host) {
			multiRepoHosts = append(multiRepoHosts, k)
		} else {
			seenHosts = append(seenHosts, v.authURL.Host)
		}
	}

for _, k := range dc.order {
	v := dc.entries[k]
    useHttpPath := slices.Contains(multiRepoHosts, k)
	gitConfigs = append(gitConfigs, v.configBlurb(k, useHttpPath))
}

That being said, there is another risk which is worth discussing: suppose I have a shared auth key for all my org's repos https://gitea.com/athorp/*, and a second key for some other private repo https://gitea.com/secret/repo. In this case I think the "correct" way to configure my gitConfig would be to

1. Set useHttpPath = true only for the standalone repo
2. Ensure the shared credential was last in the list.

[credential "https://gitea.com/secret/repo"]
  username = foo
  useHttpPath = true

[credential "https://gitea.com"]
  username = athorp
  useHttpPath = false 

I don't know if we want to get into mixing up the order of the credentials or if we should simply document how the order matters. IMO all useHttpPath = true credentials should be ordered before any useHttpPath = false credentials, but I could see counterarguments. Either way, if we ensure useHttpPath is only set when there is a path on the provided URL, then there is at least a way for the user to configure a shared credential alongside a one-off credential using the secret order and annotations:

apiVersion: v1
kind: Secret
metadata:
  name: mutli-repo-secret
  annotations:
    tekton.dev/git-0: https://gitea.com  # <- No path to ensure useHttpPath is not set in the gitconfig
...

apiVersion: v1
kind: Secret
metadata:
  name: specific-repo-secret
  annotations:
    tekton.dev/git-0: https://gitea.com/secret/repo.git
...

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build
secrets:
  - name: specific-repo-secret
  - name: multi-repo-secret  # <- if we don't reorder the credentials, the multi-repo-secret must be listed after the specific-repo-recret

[vdemeester]

Ah that's some very good point @aThorp96 and it feels a bit complicated to handle...

[aThorp96]

We could split the difference?

If any git basic-auth credential has a path in its tekton.dev/git-x annotation, assume the path is specific and add the useHttpPath setting and leave the ordering and specificity up to the user.

We'll need to document that the (already required) ordering numbers impact credential selection (or does the secret-list order determine that?), and repo-specific credentials should be ordered before host-wide credentials (if both are used side by side.) If a user wants to use multiple credentials which are each authorized for multiple repos, each necessary would regretfully need to be enumerated.

What do you think about this approach, @vdemeester @ab-ghosh ?

[ab-ghosh]

Thank you @aThorp96 for the detailed analysis.
The path-based approach looks good to me. It's straightforward as if the annotation URL has a path, we set useHttpPath=true, otherwise we don't. This keeps the implementation simple and gives users explicit control through their URL structure. We can document the ordering behavior and provide clear examples for both single-repo and multi-repo scenarios. I think this strikes the right balance between solving the bug and maintaining backwards compatibility.
Looking forward to hearing @vdemeester thoughts on this

[vdemeester]

I think that can make sense indeed. From the official Git documentation, credential helpers match in this order:

1. Most specific match wins when using credential contexts
2. Git processes credential helpers in the order configured
3. The last matching helper is used

So we need to be very careful with the order, but I think we can determine it ?

[vdemeester]

From the https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage:
"When looking for credentials for a particular host, Git will query them in order, and stop after the first answer is provided."
And from https://git-scm.com/docs/gitcredentials:
"If there are multiple instances of the credential.helper configuration variable, each helper will be tried in turn, and may provide a

I misread a bit 🙃 , order is important, and we need to be very clear about this in documentation, and heavily test this. Let's iterate on this 👼🏼

[aThorp96]

It sounds then like we're in agreement with the next steps:

• if the secret's tekton.dev/git-\d annotation has a path after the hostname, set useHttpPath in its credentials entry
• test and confirm the necessary order when multiple credentials (one repo-specific credential, one hostname-wide credential) are used:
  • Does the order of the secrets in the SA matter, or does the number in the annotation matter? Do they both metter?
• Update the existing documentation to describe the behavior and how to properly order multiple credentials including examples

[ab-ghosh]

I've implemented the requested changes.
For the first point, when a secret's tekton.dev/git-* annotation includes a path after the hostname (e.g., https://github.com/org/repo), it now automatically sets useHttpPath = true in the corresponding .gitconfig credential entry. This enables Git to match credentials based on the full repository URL rather than just the hostname.

Regarding the ordering - after testing, I discovered that neither the order of secrets in the ServiceAccount nor the annotation number matters. This is because I've implemented automatic sorting of credentials in the .git-credentials file. The sorting ensures that host-only credentials (without a path) are always placed first, serving as fallbacks, while repo-specific credentials (with a path) are placed last. This ordering is critical because Git's credential store returns the first matching entry when queried. Without this sorting, if a repo-specific credential appeared first in .git-credentials, it could incorrectly match host-only queries (when useHttpPath=false), causing the wrong token to be used. With automatic sorting, users don't need to worry about the order of secrets in their ServiceAccount or the annotation numbering - it just works correctly regardless of how they configure it.

I've also updated the documentation in docs/auth.md with a new section explaining how to use multiple credentials for different repositories on the same host, including examples for both repo-specific only and mixed (repo-specific + host-wide fallback) configurations.

[ab-ghosh]

Test Scenarios
Scenario 1: Multiple Repo-Specific Credentials (Same Host)

Two different repositories on github.com, each with its own fine-grained PAT.
ServiceAccount Configuration:

secrets:
  - name: github-repo1-credentials     # tekton.dev/git-0: https://github.com/user/repo-1
  - name: github-repo2-credentials    # tekton.dev/git-0: https://github.com/user/repo-2

Generated ~/.gitconfig:

 [credential]
	helper = store
[credential "https://github.com/user/repo-1"]
	username = user
	useHttpPath = true
[credential "https://github.com/user/repo-2"]
	username = user	
	useHttpPath = true

• Both TaskRuns succeeded!

Scenario 2: Mixed Credentials (Repo-Specific First in ServiceAccount)

One repo-specific credential + one host-wide fallback credential.
ServiceAccount Configuration:

secrets:
  - name: repo-specific-secret      # tekton.dev/git-0: https://github.com/user/demo-repo-1
  - name: host-wide-secret           # tekton.dev/git-0: https://github.com

Generated ~/.gitconfig:

[credential]
	helper = store
[credential "https://github.com/user/repo-1"]
	username = user
	useHttpPath = true
[credential "https://github.com"]
	username = user

Note: Host-wide credential is automatically placed first regardless of ServiceAccount order.

• Both TaskRuns succeeded!

Scenario 3: Mixed Credentials (Host-Wide First in ServiceAccount)

Same secrets as Scenario 2, but with reversed order in ServiceAccount.
ServiceAccount Configuration:

secrets:
  - name: host-wide-secret      # tekton.dev/git-0: https://github.com
  - name: repo-specific-secret  # tekton.dev/git-0: https://github.com/user/demo-repo-1

Generated ~/.gitconfig:

[credential]
	helper = store
[credential "https://github.com"]
	username = user
[credential "https://github.com/user/repo-1"]
	username = user
	useHttpPath = true

Note: Despite different ServiceAccount order, .git-credentials is identical to Scenario 2

• Both TaskRuns succeeded! Order in ServiceAccount does NOT matter.

[vdemeester]

@ab-ghosh hmm looking at the CI, you may need to rebase from upstream/main to clean it up.

[waveywaves]

@ab-ghosh can you check the example you have added it's failing --- FAIL: TestExamples/v1/taskruns/git-basic-auth-multiple-repos (4.59s)

[ab-ghosh]

@waveywaves Thanks for catching that!! The example file was being picked up by TestExamples. Since this example uses placeholder credentials and non-existent repos, it was failing. I've moved the example to examples/v1/taskruns/no-ci/ which is excluded from CI test runs.

[vdemeester]

hmmm @ab-ghosh you might need to rebase again (for e2e-tests to be there)

[vdemeester]

/approve

[tekton-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: vdemeester

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [vdemeester]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[waveywaves]

@ab-ghosh let's not skip the e2e test for this ? We might have to use gitea for this.

[waveywaves]

/hold

[vdemeester]

We are waiting for #9442 to get merged before removing the hold on this one.