Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/r-lib/gh
Minimalistic GitHub API client in R
https://github.com/r-lib/gh
github github-api r
Last synced: about 2 hours ago
JSON representation
Minimalistic GitHub API client in R
- Host: GitHub
- URL: https://github.com/r-lib/gh
- Owner: r-lib
- License: other
- Created: 2015-06-08T03:00:11.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2024-10-25T13:33:02.000Z (3 months ago)
- Last Synced: 2024-12-24T13:09:21.502Z (about 1 month ago)
- Topics: github, github-api, r
- Language: R
- Homepage: https://gh.r-lib.org
- Size: 7.97 MB
- Stars: 223
- Watchers: 9
- Forks: 52
- Open Issues: 10
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- jimsghstars - r-lib/gh - Minimalistic GitHub API client in R (R)
README
---
output: github_document
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# gh
[](https://github.com/r-lib/gh/actions)
[](https://app.codecov.io/gh/r-lib/gh?branch=main)
[](https://www.r-pkg.org/pkg/gh)
[](https://www.r-pkg.org/pkg/gh)
[](https://github.com/r-lib/gh/actions/workflows/R-CMD-check.yaml)
Minimalistic client to access GitHub's
[REST](https://docs.github.com/rest) and [GraphQL](https://docs.github.com/graphql) APIs.
## Installation and setup
Install the package from CRAN as usual:
```{r eval = FALSE}
install.packages("gh")
```
Install the development version from GitHub:
```{r eval = FALSE}
pak::pak("r-lib/gh")
```
### Authentication
The value returned by `gh::gh_token()` is used as Personal Access Token
(PAT). A token is needed for some requests, and to help with rate limiting.
gh can use your regular git credentials in the git credential store, via
the gitcreds package. Use `gitcreds::gitcreds_set()` to put a PAT into the
git credential store. If you cannot use the credential store, set the
`GITHUB_PAT` environment variable to your PAT. See the details in the
`?gh::gh_token` manual page and the manual of the gitcreds package.
### API URL
* The `GITHUB_API_URL` environment variable, if set, is used for the default github api url.
## Usage
```{r}
library(gh)
```
Use the `gh()` function to access all API endpoints. The endpoints are
listed in the [documentation](https://docs.github.com/rest).
The first argument of `gh()` is the endpoint. You can just copy and paste the
API endpoints from the documentation. Note that the leading slash
must be included as well.
From you can copy and paste `GET /users/{username}/repos` into your `gh()`
call. E.g.
```{r}
my_repos <- gh("GET /users/{username}/repos", username = "gaborcsardi")
vapply(my_repos, "[[", "", "name")
```
The JSON result sent by the API is converted to an R object.
Parameters can be passed as extra arguments. E.g.
```{r}
my_repos <- gh(
"/users/{username}/repos",
username = "gaborcsardi",
sort = "created")
vapply(my_repos, "[[", "", "name")
```
### POST, PATCH, PUT and DELETE requests
POST, PATCH, PUT, and DELETE requests can be sent by including the
HTTP verb before the endpoint, in the first argument. E.g. to
create a repository:
```{r eval = FALSE}
new_repo <- gh("POST /user/repos", name = "my-new-repo-for-gh-testing")
```
and then delete it:
```{r eval = FALSE}
gh("DELETE /repos/{owner}/{repo}", owner = "gaborcsardi",
repo = "my-new-repo-for-gh-testing")
```
### Tokens
By default the `GITHUB_PAT` environment variable is used. Alternatively,
one can set the `.token` argument of `gh()`.
### Pagination
Supply the `page` parameter to get subsequent pages:
```{r}
my_repos2 <- gh("GET /orgs/{org}/repos", org = "r-lib", page = 2)
vapply(my_repos2, "[[", "", "name")
```
## Environment Variables
* The `GITHUB_API_URL` environment variable is used for the default github
api url.
* The `GITHUB_PAT` and `GITHUB_TOKEN` environment variables are used, if
set, in this order, as default token. Consider using the git credential
store instead, see `?gh::gh_token`.
## Code of Conduct
Please note that the gh project is released with a
[Contributor Code of Conduct](https://gh.r-lib.org/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.
## License
MIT © Gábor Csárdi, Jennifer Bryan, Hadley Wickham