EVOLUTION-MANAGER

Edit File: managing-personal-access-tokens.html

<!DOCTYPE html>

<html>

<head>

<title>Managing Personal Access Tokens</title>

</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>

</head>

<body>

<h1 class="title toc-ignore">Managing Personal Access Tokens</h1>

<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">library</span>(gh)</span></code></pre></div>

<p>gh generally sends a Personal Access Token (PAT) with its requests.
Some endpoints of the GitHub API can be accessed without authenticating
yourself. But once your API use becomes more frequent, you will want a
PAT to prevent problems with rate limits and to access all possible
endpoints.</p>
<p>This article describes how to store your PAT, so that gh can find it
(automatically, in most cases). The function gh uses for this is
<code>gh_token()</code>.</p>
<p>More resources on PAT management:</p>
<ul>
<li>GitHub documentation on <a href="https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token">Creating
a personal access token</a></li>
<li>In the <a href="https://usethis.r-lib.org">usethis package</a>:
<ul>
<li>Vignette: <a href="https://usethis.r-lib.org/articles/articles/git-credentials.html">Managing
Git(Hub) Credentials</a></li>
<li><code>usethis::gh_token_help()</code> and
<code>usethis::git_sitrep()</code> help you check if a PAT is
discoverable and has suitable scopes</li>
<li><code>usethis::create_github_token()</code> guides you through the
process of getting a new PAT</li>
</ul></li>
<li>In the <a href="https://gitcreds.r-lib.org/">gitcreds package</a>:
<ul>
<li><code>gitcreds::gitcreds_set()</code> helps you explicitly put your
PAT into the Git credential store</li>
</ul></li>
</ul>
<div id="pat-and-host" class="section level2">
<h2>PAT and host</h2>
<p><code>gh::gh()</code> allows the user to provide a PAT via the
<code>.token</code> argument and to specify a host other than
“github.com” via the <code>.api_url</code> argument. (Some companies and
universities run their own instance of GitHub Enterprise.)</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="fu">gh</span>(endpoint, ..., <span class="at">.token =</span> <span class="cn">NULL</span>, ..., <span class="at">.api_url =</span> <span class="cn">NULL</span>, ...)</span></code></pre></div>
<p>However, it’s annoying to always provide your PAT or host and it’s
unsafe for your PAT to appear explicitly in your R code. It’s important
to make it <em>possible</em> for the user to provide the PAT and/or API
URL directly, but it should rarely be necessary. <code>gh::gh()</code>
is designed to play well with more secure, less fiddly methods for
expressing what you want.</p>
<p>How are <code>.api_url</code> and <code>.token</code> determined when
the user does not provide them?</p>
<ol style="list-style-type: decimal">
<li><code>.api_url</code> defaults to the value of the
<code>GITHUB_API_URL</code> environment variable and, if that is unset,
falls back to <code>&quot;https://api.github.com&quot;</code>. This is always done
before worrying about the PAT.</li>
<li>The PAT is obtained via a call to <code>gh_token(.api_url)</code>.
That is, the token is looked up based on the host.</li>
</ol>
</div>
<div id="the-gitcreds-package" class="section level2">
<h2>The gitcreds package</h2>
<p>gh now uses the gitcreds package to interact with the Git credential
store.</p>
<p>gh calls <code>gitcreds::gitcreds_get()</code> with a URL to try to
find a matching PAT. <code>gitcreds::gitcreds_get()</code> checks
session environment variables and then the local Git credential store.
Therefore, if you have previously used a PAT with, e.g., command line
Git, gh may retrieve and re-use it. You can call
<code>gitcreds::gitcreds_get()</code> directly, yourself, if you want to
see what is found for a specific URL.</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>gitcreds<span class="sc">::</span><span class="fu">gitcreds_get</span>()</span></code></pre></div>
<p>If you see something like this:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="co">#&gt; &lt;gitcreds&gt;</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="co">#&gt;   protocol: https</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="co">#&gt;   host    : github.com</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="co">#&gt;   username: PersonalAccessToken</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="co">#&gt;   password: &lt;-- hidden --&gt;</span></span></code></pre></div>
<p>that means that gitcreds could get the PAT from the Git credential
store. You can call <code>gitcreds_get()$password</code> to see the
actual PAT.</p>
<p>If no matching PAT is found, <code>gitcreds::gitcreds_get()</code>
errors.</p>
</div>
<div id="pat-in-an-environment-variable" class="section level2">
<h2>PAT in an environment variable</h2>
<p>If you don’t have a Git installation, or your Git installation does
not have a working credential store, then you can specify the PAT in an
environment variable. For <code>github.com</code> you can set the
<code>GITHUB_PAT_GITHUB_COM</code> or <code>GITHUB_PAT</code> variable.
For a different GitHub host, call
<code>gitcreds::gitcreds_cache_envvar()</code> with the API URL to see
the environment variable you need to set. For example:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a>gitcreds<span class="sc">::</span><span class="fu">gitcreds_cache_envvar</span>(<span class="st">&quot;https://github.acme.com&quot;</span>)</span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="co">#&gt; [1] &quot;GITHUB_PAT_GITHUB_ACME_COM&quot;</span></span></code></pre></div>
</div>
<div id="recommendations" class="section level2">
<h2>Recommendations</h2>
<p>On a machine used for interactive development, we recommend:</p>
<ul>
<li><p>Store your PAT(s) in an official credential store.</p></li>
<li><p>Do <strong>not</strong> store your PAT(s) in plain text in, e.g.,
<code>.Renviron</code>. In the past, this has been a common and
recommended practice for pragmatic reasons. However, gitcreds/gh have
now evolved to the point where it’s possible for all of us to follow
better security practices.</p></li>
<li><p>If you use a general-purpose password manager, like 1Password or
LastPass, you may <em>also</em> want to store your PAT(s) there. Why? If
your PAT is “forgotten” from the OS-level credential store,
intentionally or not, you’ll need to provide it again when prompted.</p>
<p>If you don’t have any other record of your PAT, you’ll have to get a
new PAT whenever this happens. This is not the end of the world. But if
you aren’t disciplined about deleting lost PATs from <a href="https://github.com/settings/tokens" class="uri">https://github.com/settings/tokens</a>, you will eventually
find yourself in a confusing situation where you can’t be sure which
PAT(s) are in use.</p></li>
</ul>
<p>On a headless system, such as on a CI/CD platform, provide the
necessary PAT(s) via secure environment variables. Regular environment
variables can be used to configure less sensitive settings, such as the
API host. Don’t expose your PAT by doing something silly like dumping
all environment variables to a log file.</p>
<p>Note that on GitHub Actions, specifically, a personal access token is
<a href="https://docs.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token">automatically
available to the workflow</a> as the <code>GITHUB_TOKEN</code> secret.
That is why many workflows in the R community contain this snippet:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="fu">env</span><span class="kw">:</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="fu">GITHUB_PAT</span><span class="kw">:</span><span class="at"> ${{ secrets.GITHUB_TOKEN }}</span></span></code></pre></div>
<p>This makes the automatic PAT available as the <code>GITHUB_PAT</code>
environment variable. If that PAT doesn’t have the right permissions,
then you’ll need to explicitly provide one that does (see link above for
more).</p>
</div>
<div id="failure" class="section level2">
<h2>Failure</h2>
<p>If there is no PAT to be had, <code>gh::gh()</code> sends a request
with no token. (Internally, the <code>Authorization</code> header is
omitted if the PAT is found to be the empty string,
<code>&quot;&quot;</code>.)</p>
<p>What do PAT-related failures look like?</p>
<p>If no PAT is sent and the endpoint requires no auth, the request
probably succeeds! At least until you run up against rate limits. If the
endpoint requires auth, you’ll get an HTTP error, possibly this one:</p>
<pre><code>GitHub API error (401): 401 Unauthorized
Message: Requires authentication</code></pre>
<p>If a PAT is first discovered in an environment variable, it is taken
at face value. The two most common ways to arrive here are PAT
specification via <code>.Renviron</code> or as a secret in a CI/CD
platform, such as GitHub Actions. If the PAT is invalid, the first
affected request will fail, probably like so:</p>
<pre><code>GitHub API error (401): 401 Unauthorized
Message: Bad credentials</code></pre>
<p>This will also be the experience if an invalid PAT is provided
directly via <code>.token</code>.</p>
<p>Even a valid PAT can lead to a downstream error, if it has
insufficient scopes with respect to a specific request.</p>
</div>

<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>