use gitcreds for managing github PAT

[Aariq]

Description

Still a WIP, but this PR aims to re-write the gist_auth() function to take advantage of gitcreds::gitcreds_get() which finds github PATs stored either in the GITHUB_PAT env var or stored with gitcreds::gitcreds_set()

Changes:

• Update function documentation
• Add tests (these rely on an env var existing, so might not work locally, but should work on GitHub)
• Add my name as a contributor to DESCRIPTION (if that's ok)
• Updates NEWS.md

Would be nice:

• Have gist_auth() check that the PAT has gist scope

Related Issue

closes #95

Example

[ScientificProgrammer]

Nice work. In this instance, the CI/CD checks failed, which I'm assuming is due to them needing to be updated. I will take a look at them and see if I can get them working again.

[ScientificProgrammer]

I figured out that the reason the checks failed is because you didn't have the correct OAuth token for the CI/CD workflows. I'll see if I can generate one and run the tests myself.

[ScientificProgrammer]

@maelle

I'm having trouble creating an OAuth token for the CI/CD workflows, and I don't want to force push to the main branch. Please let me know your availability for the rest of today and the rest of this week.

[Aariq]

I can also take a look at this while I finish up this PR. I would think that the built-in PAT that GitHub actions uses would have gist scope. Please do wait to merge this until it is no longer a "draft" and we get the checks passing.

[Aariq]

Yeah, looks like the built-in GITHUB_TOKEN secret doesn't have 'gist' permission by default. I'll see if I can get these permissions fixed in the workflow. I'm not confident that's all that is going wrong though, as these tests do not pass locally either.

[ScientificProgrammer]

I just tried to add it, and I updated the yaml file at .github/workflows/R-CMD-check.yaml. I'll see if I can run the workflows and get them to pass.

[Aariq]

So I thought you could add the "gist" scope with the permissions: key in a workflow, but apparently not.

I take it the GIST_TOKEN secret you created has all the required permissions though, so I'll try something else.

[ScientificProgrammer]

@Aariq The checks are failing because the current tokens do not have gist management permissions. I tried creating my own fine-grained PAT with the appropriate gist scope and installing it as a secret, but I think someone from rOpenSci is going to have to create an organizational token for us. I also tried to implement my code changes on top of yours in the hopes of simplifying things. However, without the PAT with the correct permissions, it's a moot point. Thus, feel free to roll back my changes or let me know if you'd like for me to do so.

[Aariq]

Huh, I think I'm either misunderstanding something about gitcreds, or misunderstanding something about GitHub Actions. I added a test just to see if gitcreds_get() could retrieve a token set as the GITHUB_PAT env var by the workflow file and it fails with:

── Error ('test-gist_auth.R:2:3'): gitcreds finds PAT ──────────────────────────
<gitcreds_no_credentials/gitcreds_error/error/condition>
Error in `throw(new_error("gitcreds_no_credentials", url = url))`: Could not find any credentials

So either gitcreds_get() doesn't actually look at env vars as a backup when there is nothing in the credential store (and it just seems to work like that locally because of caches or something) or the workflow isn't setting the GITHUB_PAT env var like I think it does

[Aariq]

test_that("PAT gets found", {
  expect_equal(gitcreds::gitcreds_get()$password, Sys.getenv("GITHUB_PAT"))
  expect_equal(gistr::gist_auth()$Authorization, paste0("token ", Sys.getenv("GITHUB_PAT")))
})

I was able to get the above simple tests passing in a dummy package by doing the following:

1. Create a new PAT with usethis::create_github_token() with the default scopes it specifies which include "gist" (no idea if the other scopes are required for this to work)
2. Store that PAT as a secret by going to Settings > Secrets and Variables > Actions > New Repository Secret. I gave it the name TOKEN_GIST and pasted the PAT in.
3. Edited R-CMD-check.yaml to change GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} to GITHUB_PAT: ${{ secrets.TOKEN_GIST }}

I think the same should work here.

[ScientificProgrammer]

@Aariq,

It seems we may be addressing two separate issues here, so I’ll elaborate on each below.

Issue 1: Testing gistr's use of git_creds() on a local user’s machine

On this first point, I believe you have it resolved. To clarify, git_creds() effectively manages the complexity introduced by different credential types, such as SSH keys or PATs, as well as OS-specific challenges in how credentials are stored and accessed. This management is further complicated by a user’s git configuration, which may involve system, user, directory, or repo-level settings.

For instance, depending on whether they are on Windows, macOS, or Linux, a user might be using a credential management agent, such as an SSH agent, keychain, or keyring. If the agent doesn’t hold a valid credential for a given gist, the system may fall back to another authentication method, like an environment variable, an SSH key, or a PAT.

The management of these credentials can vary significantly based on the OS and user-specific setup. For example, on Windows, the git-bash installer typically offers two main options:

1. Git Credential Manager (my preferred choice),
2. Windows credential store (wincreds).

Aside from these, users may also configure other credential managers, such as a standard SSH agent or keychain. Regardless of the OS or configuration details, it’s ultimately the user’s responsibility to ensure their setup works as intended.

In terms of git_creds() itself, you likely have deeper insights than I do, so I’ll defer to your experience. However, in my own experience, git_creds() has consistently provided a streamlined interface in R that effectively abstracts away the complexities of interacting with the system’s git credential management infrastructure, regardless of how that infrastructure is implemented.

Issue 2: CI/CD Check Failures on PR #96

Regarding the CI/CD checks on your pull request, it seems they’re failing because both you and I need an organizational token to allow the workflows to create a gist for testing purposes. Despite being a maintainer, I currently lack permissions to create the credential or secret necessary for the CI/CD workflow to function correctly.

From what I’ve researched, maintainers of organizational repositories are often given the ability to create CI/CD credentials, but when this isn’t the case, someone with the required permissions within the organization will need to create the credentials. Since ropensci/gistr is managed by rOpenSci, we’ll need to coordinate with someone who can generate this credential for us. They would either provide it to us for installation or install it directly as a secret.

I suspect that prior maintainers may have had such credentials, and the current CI/CD issues could be due to one of the following:

1. Expired credentials,
2. Credentials deleted or invalidated during the transition between maintainers, or
3. The existing credentials lacking the required authorization scope for the actions being attempted.

The most likely causes are 1 or 2. Regarding point 3, although we’re working as a team, the specific changes were made by you, and upon reviewing them, I didn’t see anything that would exceed the previously invoked CI/CD scope.

---

If any part of this seems off base, please let me know. I’d be happy to schedule a session to go over it together. I’m also trying to arrange a discussion with @maelle for tomorrow (Thursday, 2024-11-07) or Friday (2024-11-08) to update the maintainer designation with CRAN for this repo.

Ideally, I’d like to get the three of us on the same call to tackle both issues at once. Thanks again for all the great work you’re doing!

---

Notes for Comment Revisions

num	time	notes
1	2024-11-07 11:16 GMT-6	Posting the corrected version of my response. For the previous version, I inadvertently posted my first draft. The version is the one I meant to post.

[Aariq]

I think you could just use a PAT you create for your own account to get the tests to pass, but I understand why you wouldn't want to do that—it apparently fills up your gists with a bunch of artifacts from the tests running.

[maelle]

Why not mock the tests instead? Not that's it's super easy either, but it might solve the problem of having tests that create and delete gists. https://books.ropensci.org/http-testing/

[maelle]

Regarding secrets, if a PAT is created for this repo, it will only be accessible for workflow runs from this repository, that is to say, not from external PRs.

[maelle]

it should be both aut and cre, "cre" would then be removed from Scott's roles

[maelle]

see what usethis does https://github.com/r-lib/usethis/blob/50dcb10cf5fc69d456176cfb66b4d19f81e12bf4/R/github_token.R#L254

[maelle]

this could also point to https://usethis.r-lib.org/reference/github-token.html as the functions are quite handy

[maelle]

instead, why not directly test it works, using a call to https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user