post: end of post

posts/2024-03-12-storing-secrets-with-the-renviron-file/2024-03-12-storing-secrets-with-the-renviron-file.qmd

@@ -42,29 +42,79 @@ In short, it is a way to pass information to a program. Environment variable are
 
 ## The .Renviron file
 
-The [{{< fa brands r-project >}} startup process](https://rstats.wtf/r-startup.html) is complex. But one special {{< fa brands r-project >}} file is interesting for our purpose: the `.Renviron` file. This file does not contain {{< fa brands r-project >}} code: it only contains environment variables that will be pass to {{< fa brands r-project >}} at the startup.
+The [{{< fa brands r-project >}} startup process](https://rstats.wtf/r-startup.html) is complex but one special {{< fa brands r-project >}} file is interesting for our purpose: the `.Renviron` file. This file does not contain {{< fa brands r-project >}} code: it only contains environment variables that will be pass to {{< fa brands r-project >}} at startup. It looks like:
 
-The `.Renviron` file looks like:
-
-```
+```txt
 NAME1=value1
 NAME2=value2
 ```
 
-To open (and create this `~/.Renviron`), run this command:
+We can use this file to store our secrets. To open (and create) this `.Renviron` file, run this command:
 
 ```{r}
 #| eval: false
 
 ## Create (if required) and open ~/.Renviron file ----
 utils::file.edit("~/.Renviron")
+
+## Alternatively,
+usethis::edit_r_environ()
+```
+
+This command will create an `.Renviron` file at the user level (i.e. in his/her `HOME` directory) and all environment variables defined inside will be available for all his/her projects.
+
+To store a new secret, just add a new line. For instance:
+
+```txt
+GITHUB_PAT='ghp_9999zzz9999zzz'
+```
+
+**N.B.** add a new empty line at the end of this file otherwise {{< fa brands r-project >}} will ignore it.
+
+
+## Accessing secrets
+
+To retrieve the value of a secret (and any environment variable), just use the function [`Sys.getenv()`](https://stat.ethz.ch/R-manual/R-patched/library/base/html/Sys.getenv.html).
+
+```{r}
+#| eval: false
+
+## Get secret value ----
+Sys.getenv("GITHUB_PAT")
+
+## Handle this secret securely ----
+github_pat <- Sys.getenv("GITHUB_PAT")
 ```
 
-This command has created an user `.Renviron` file in his/her `HOME` directory.
+**N.B.** by running `Sys.getenv()` without argument you will print all available envrionment variables.
+
+
+## To go further
 
 A `.Renviron` file can be created at three different levels:
 
 - at the system level (named `.Renviron.site`)
 - at the user level (`~/.Renviron`)
 - at the project level (`.Renviron`)
 
+At startup {{< fa brands r-project >}} will first read `.Renviron.site`, then `~/.Renviron` and finally the `.Renviron` of the project.
+This means that if the same environment variable is defined in `~/.Renviron` (user level) and in the `.Renviron` of the project, the value defined in the `.Renviron` of the project will overwrite the one defined at the user level.
+
+- If you want to store a secret that be shared among projects, store it in the `~/.Renviron` (user level)
+- If you want to store a secret specific to a project, store it in the `.Renviron` (project level)
+
+
+::: {.callout-important}
+## `git` and `.Renviron`
+
+If you create a `.Renviron` file at the project level, **do not forget** to add this file to the `.gitignore`. Otherwise your secret will be published on GitHub.
+:::
+
+
+## Resources
+
+<https://rstats.wtf/r-startup.html><br>
+<https://resources.numbat.space/using-.rprofile-and-.html><br>
+<https://cran.r-project.org/web/packages/httr/vignettes/secrets.html><br>
+<https://www.r-bloggers.com/2024/02/key-advantages-of-using-the-keyring-package/>
+