{"id":19692198,"url":"https://github.com/getgrav/grav-plugin-github","last_synced_at":"2026-03-04T21:32:12.428Z","repository":{"id":19970944,"uuid":"23237960","full_name":"getgrav/grav-plugin-github","owner":"getgrav","description":"Grav GitHub Plugin","archived":false,"fork":false,"pushed_at":"2020-12-15T17:42:16.000Z","size":1662,"stargazers_count":13,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2025-10-22T12:35:28.080Z","etag":null,"topics":["github","grav","grav-plugin"],"latest_commit_sha":null,"homepage":"https://getgrav.org","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getgrav.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-22T19:53:47.000Z","updated_at":"2023-06-10T21:43:13.000Z","dependencies_parsed_at":"2022-07-08T01:05:17.257Z","dependency_job_id":null,"html_url":"https://github.com/getgrav/grav-plugin-github","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/getgrav/grav-plugin-github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-github","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-github/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-github/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-github/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getgrav","download_url":"https://codeload.github.com/getgrav/grav-plugin-github/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgrav%2Fgrav-plugin-github/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30093788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T20:42:30.420Z","status":"ssl_error","status_checked_at":"2026-03-04T20:42:30.057Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","grav","grav-plugin"],"created_at":"2024-11-11T19:12:35.433Z","updated_at":"2026-03-04T21:32:12.330Z","avatar_url":"https://github.com/getgrav.png","language":"PHP","readme":"# Grav GitHub Plugin\n\n`GitHub` is a [Grav][grav] Plugin that wraps the [GitHub v3 API][github-api].\n\nThe plugin itself relies on the [php-github-api][php-github-api] library to wrap GitHub.\n\n# Installation\n\nInstalling the GitHub plugin can be done in one of two ways. Our GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple cli command, while the manual method enables you to do so via a zip file.\n\n## GPM Installation (Preferred)\n\nThe simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's Terminal (also called the command line). From the root of your Grav install type:\n\n    $ bin/gpm install github\n\nThis will install the GitHub plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/github`.\n\n## Manual Installation\n\nTo install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `github`. You can find these files either on [GitHub](https://github.com/getgrav/grav-plugin-github) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).\n\nYou should now have all the plugin files under\n\n    /your/site/grav/user/plugins/github\n\n\u003e\u003e NOTE: You might benefit from an additional layer of cache by using this plugin in combination with the [twigcache plugin][twigcache].\n\n# Usage\n\nTo use `github`, you will need to trigger the plugin by adding the `github: true` setting in the header of the main page.\n\n```\n---\ntitle: GitHub\ngithub: true\n---\n\n# My GitHub page\n```\n\nYou can use the `github` api from the _github.md_ file by enabling the _twig processing_ in the header, right where you added the `github: true`.\n\n```\nprocess:\n    twig: true\n```\n\nThe _github.md_ file will be loading the [_github.html.twig_][github.html.twig] that is provided by the plugin and that contains some useful examples to get started.\n\nAlthough if you use a template, or override the default one, it is more efficient and fast.\n\nIf you want to override the [_github.html.twig_][github.html.twig], copy the template file into the templates folder of your custom theme and that is it.\n\n```\n/your/site/grav/user/themes/custom-theme/templates/github.html.twig\n```\n\nYou can now edit the override and tweak it to meet your needs.\n\n\n# Authentication\n\nGitHub API has a limit imposed to 60 requests per hour when the API is interrogated as a guest. However, when authenticated, this limit is bumped to 5000 requests per hour.\n\n`grav-plugin-github` provides a [configuration](github.yaml) for the authentication. You can create a `user/config/plugins/github.yaml` file and compile all the required fields.\n\nThere are two methods of authentication: `api` and `password`.\n\n## API (adviced)\n\nWhen deciding to use the API method, it is necessary to generate a _Personal Access Token_ from GitHub (https://github.com/settings/tokens). Click the _Generate new token_ button and you will be presented with a form where you can give your token a name as well as configure the permissions.\n\nBe very careful about the permissions, allowing all is almost never what you really want. If you are planning to just read data, just limit the permissions to read access points, and so on.\n\nOnce you have generated your access token, it will be shown to you. Be adviced that this will be the first and only time you will ever see the token on GitHub. It is not possible to retrieve a token, however you can store it someplace safe of your own or, if lost, it can be regenerated.\n\nWith the token in hand, head back to the previously created `github.yaml` file and configure it as so:\n\n``` yaml\nenabled: true\nauth:\n    method: 'api'\n    token: 'abcd1234...'\n```\n\n\u003e The password field is not needed when using the API method\n\n\n## Password (`CAUTION!`)\n\nYou can decide to authenticate through a credential method, the same way you would do when logging into GitHub.\n\nDue to the nature of Grav, being flat-file and database free, this means your password will have to be written in plain text and it can potentially get exposed to unauthorized people.\n\nIt is **STRONGLY** adviced to never use this method of authentication but, if you really want to, this is how you would compile the `github.yaml` file that was previously created.\n\n``` yaml\nenabled: true\n    method: 'password'\n    token: 'username'\n    password: 'your_password'\n```\n\n# Examples\nA few examples. Note that the APIs are based on [php-github-api][php-github-api] which uses the [GitHub v3 API][github-api]. Refer to their docs for additional informations.\n\n### List _stargazers_ count of a repository\n```\nGrav has currently \u003cstrong\u003e{{ github.client.api('repo').show('getgrav', 'grav')['stargazers_count'] }} stargazers\u003c/strong\u003e\n```\n\n### List all the _repositories_ of a user\nLists all the repositories of a user and for each of them shows the link to GitHub, the forks count and the stargazers count.\n\n```\n\u003cul\u003e\n    \u003cli\u003eRepositories (\u003cstrong\u003e{{ github.client.api('user').repositories('getgrav')|length }}\u003c/strong\u003e):\n        \u003cul\u003e\n        {% for repo in github.client.api('user').repositories('getgrav') %}\n            \u003cli\u003e{{ repo.name|e }} [\u003ca href=\"{{ repo.html_url|e }}\"\u003elink\u003c/a\u003e | forks: \u003cstrong\u003e{{ repo.forks_count|e }}\u003c/strong\u003e | stargazers: \u003cstrong\u003e{{ repo.stargazers_count|e }}\u003c/strong\u003e]\u003c/li\u003e\n        {% endfor %}\n        \u003c/ul\u003e\n    \u003c/li\u003e\n\u003c/ul\u003e\n```\n\n### Paginator: Get all _repositories_ of a organization [getgrav]\nYou can use the `paginator` to manage GitHub pages. GitHub by default limits each page to 30 items maximum, but provides an API to know if there are subsequential pages and how to reach them.\n\nRefer to the [KnpLabs/php-github-api](https://github.com/KnpLabs/php-github-api/blob/master/doc/result_pager.md) documentation for more details on how to use the pagination.\n\n``` twig\n{% set api = github.client.api('organization') %}\n{% set result = github.paginator.fetchAll(api, 'repositories', ['getgrav']) %}\n```\n\n`fetchAll` will take care of navigating through all pages and return the full stack of data that you can then cycle through.\n\nIf a more manual approach is desired, then it shall be used `fetch`, which will allow to interrogate next and previous pages as well as fetch them again.\n\n``` twig\n{% set api = github.client.api('organization') %}\n{% set result = github.paginator.fetch(api, 'repositories', ['getgrav']) %}\n```\n\nSame as the previous example, except for the `fetch` vs `fetchAll`. This call will return only the **first** page.\n\nAt this point we can interrogate the `paginator` about next and previous pages and for fetching them.\n\n### Check for next page\n\n``` twig\n{% if (github.paginator.hasNext()) %}\n```\n\n### Fetch the next page\n\n``` twig\n{% set next = github.paginator.fetchNext() %}\n```\n\n\n### Check for previous page\n\n``` twig\n{% if (github.paginator.hasPrevious()) %}\n```\n\n### Fetch the previous page\n\n``` twig\n{% set Previous = github.paginator.fetchPrevious() %}\n```\n\n# Updating\n\nAs development for the GitHub plugin continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating GitHub is easy, and can be done through Grav's GPM system, as well as manually.\n\n## GPM Update (Preferred)\n\nThe simplest way to update this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). You can do this with this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:\n\n    bin/gpm update github\n\nThis command will check your Grav install to see if your GitHub plugin is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type `y` and hit enter. The plugin will automatically update and clear Grav's cache.\n\n## Manual Update\n\nManually updating GitHub is pretty simple. Here is what you will need to do to get this done:\n\n* Delete the `your/site/user/plugins/github` directory.\n* Downalod the new version of the GitHub plugin from either [GitHub](https://github.com/getgrav/grav-plugin-github) or [GetGrav.org](http://getgrav.org/downloads/plugins#extras).\n* Unzip the zip file in `your/site/user/plugins` and rename the resulting folder to `github`.\n* Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in terminal and typing `bin/grav clear-cache`.\n\n\u003e Note: Any changes you have made to any of the files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in `user/config/plugins`) will remain intact.\n\n[grav]: http://github.com/getgrav/grav\n[github-api]: https://developer.github.com/v3/\n[php-github-api]: https://github.com/KnpLabs/php-github-api/\n[twigcache]: https://github.com/getgrav/grav-plugin-twigcache\n[github.html.twig]: templates/partials/github.html.twig\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgrav%2Fgrav-plugin-github","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetgrav%2Fgrav-plugin-github","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgrav%2Fgrav-plugin-github/lists"}