probablykasper / readme-template-action

Integrate GitHub API data in your README.md

README Template

Add GitHub data to your README.md, or any other file.

A GitHub action that provides template strings that are replaced with their respective values when the action runs.

By default, it takes TEMPLATE.md and outputs README.md.

Inputs

name	required	type	default	description
token	yes	string		GitHub personal access token used to fetch data. Pass a secret by for instance using ${{ secrets.README_TEMPLATE_TOKEN }}. Go here to generate one with the read:user scope
template	yes	string	"TEMPLATE.md"	Template file path
readme	yes	string	"README.md"	Output file path

Example usage

Check out EXAMPLE_TEMPLATE.md and EXAMPLE_OUTPUT.md for more examples and their outputs.

Workflow:

name: Readme Template
on:
  schedule:
    - cron: '0 */2 * * *' # every 2 hours
  push:
    branches: [ master ]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0
    - name: Generate README.md
      uses: probablykasper/readme-template-action@v1
      with:
        token: ${{ secrets.README_TEMPLATE_TOKEN }}
        template: TEMPLATE.md
        output: README.md
    - name: Update README.md
      run: |
        if [[ "$(git status --porcelain)" != "" ]]; then
          git config user.name "GitHub Action"
          git config user.email "[email protected]"
          git add .
          git commit -m "Auto-update README.md"
          git push
        fi

TEMPLATE.md:

My most starred repos:
| ⭐️Stars   | 📦Repo    | 📚Description |
| --------- | ----------- | -------------- |
{{ loop 3_MOST_STARRED_REPOS }}
| {{ REPO_STARS }} | [{{ REPO_FULL_NAME }}]({{ REPO_URL }}) | {{ REPO_DESCRIPTION }} |
{{ end 3_MOST_STARRED_REPOS }}

This generates the following output in my case:

My most starred repos:

⭐️Stars	📦Repo	📚Description
10	probablykasper/chester-syntax	A pretty Atom syntax theme based on Lonely Planet colours
4	probablykasper/homebrew-tap	My Homebrew casks and formulas
2	probablykasper/cryp	Cryptocurrency portfolio tracker
1	probablykasper/notifier	Flutter app for scheduling notifications
1	probablykasper/colorboy	Easy terminal coloring for Node.js, macOS/Linux

Variables

Normal variables you can put into your template file

Variable	Example
{{ USERNAME }}	probablykasper
{{ NAME }}	Kasper
{{ EMAIL }}	[email protected]
{{ USER_ID }}	MDQ6VXNlcjExMzE1NDky
{{ BIO }}	Fullstack developer from Norway
{{ COMPANY }}	Microscopicsoft
{{ LOCATION }}	Norway
{{ TWITTER_USERNAME }}	probablykasper
{{ AVATAR_URL }}	https://avatars0.githubusercontent.com/u/11315492?u=c501da00e9b817ffc78faab6c630f236ac2738cf&v=4
{{ WEBSITE_URL }}	https://kasper.space/
{{ SIGNUP_TIMESTAMP }}	2015-03-04T14:48:35Z
{{ SIGNUP_DATE }}	March 4th 2015
{{ SIGNUP_DATE2 }}	2015-03-04
{{ SIGNUP_YEAR }}	2015
{{ SIGNUP_AGO }}	5 years ago
{{ TOTAL_REPOS_SIZE_KB }}	707453
{{ TOTAL_REPOS_SIZE_MB }}	707.5
{{ TOTAL_REPOS_SIZE_GB }}	0.71
{{ TOTAL_REPOSITORIES }}	46
{{ CURRENT_REPO_FULL_NAME }}	probablykasper/readme-template-action

Variables you can put inside repo loops

Variable	Example
{{ REPO_NAME }}	cpc
{{ REPO_FULL_NAME }}	probablykasper/cpc
{{ REPO_DESCRIPTION }}	Text calculator with support for units and conversion
{{ REPO_URL }}	https://github.com/probablykasper/cpc
{{ REPO_HOMEPAGE_URL }}	https://rust-lang.org/
{{ REPO_CREATED_TIMESTAMP }}	2019-12-05T22:45:04Z
{{ REPO_PUSHED_TIMESTAMP }}	2020-08-20T20:13:22Z
{{ REPO_FORK_COUNT }}	2
{{ REPO_ID }}	MDEwOlJlcG9zaXRvcnkyMjYyMDE5NTU=
{{ REPO_CREATED_DATE }}	December 5th 2019
{{ REPO_CREATED_DATE2 }}	2019-12-05
{{ REPO_CREATED_YEAR }}	2019
{{ REPO_CREATED_AGO }}	9 months ago
{{ REPO_PUSHED_DATE }}	August 20th 2020
{{ REPO_PUSHED_DATE2 }}	2020-08-20
{{ REPO_PUSHED_YEAR }}	2020
{{ REPO_PUSHED_AGO }}	3 days ago
{{ REPO_STARS }}	5
{{ REPO_LANGUAGE }}	Rust
{{ REPO_OWNER_USERNAME }}	probablykasper
{{ REPO_SIZE_KB }}	1268285
{{ REPO_SIZE_MB }}	1268.3
{{ REPO_SIZE_GB }}	1.27

Loops

These are the built-in loops you can use. Data is only fetched for loops you use.

Loop	Type	Description
3_MOST_STARRED_REPOS	repos	Fetches your 3 most starred repos. Uses the following parameters: first: 3, privacy: PUBLIC, ownerAffiliations:[OWNER], orderBy: { field:STARGAZERS, direction: DESC }
3_NEWEST_REPOS	repos	Fetches your 3 most starred repos. Uses the following parameters: first: 3, privacy: PUBLIC, ownerAffiliations:[OWNER], orderBy: { field:CREATED_AT, direction: DESC }
3_RECENTLY_PUSHED_REPOS	repos	Fetches your 3 most starred repos. Uses the following parameters: first: 3, privacy: PUBLIC, ownerAffiliations:[OWNER], orderBy: { field:PUSHED_AT, direction: DESC }

Advanced usage

Check out EXAMPLE_TEMPLATE.md and EXAMPLE_OUTPUT.md to see examples and their outputs.

For advanced usage, add a code block like this to your template:

```js
// {{ TEMPLATE: }}
module.exports = {
    // ... custom vairables/loops
}
// {{ :TEMPLATE }}

List specific repos

Get a list of specific repos

  CUSTOM_PINNED_REPOS: {
    type: 'specificRepos',
    repos: [ 'vidl', 'golang/go', 'probablykasper/embler' ],
  },

Repos with custom parameters

Get repos using custom parameters:

  "2_MOST_STARRED_REPOS": {
    type: 'repos',
    params: `
      first: 2,
      privacy: PUBLIC,
      ownerAffiliations:[OWNER],
      orderBy: { field:STARGAZERS, direction: DESC },
    `,
  },

Modify variables

Add a modifyVariables function to overwrite/add variables:

  CUSTOM_PINNED_REPOS: {
    type: 'specificRepos',
    repos: [ 'vidl' ],
    modifyVariables: function(repo, moment, user) {
      repo.REPO_CREATED_MYDATE = moment(repo.REPO_CREATED_TIMESTAMP).format('YYYY MMMM Do')
      return repo
    },
  },

Custom queries

  LATEST_VIDL_RELEASE: {
    type: 'customQuery',
    loop: false,
    query: async (octokit, moment, user) => {
      // You can do anything  you want with the GitHub API here.
      const result = await octokit.graphql(`
        query {
          repository(name: "vidl", owner: "${user.USERNAME}") {
            releases(last: 1) {
              edges {
                node {
                  url
                  publishedAt
                  tagName
                }
              }
            }
          }
        }
      `)
      const release = result.repository.releases.edges[0].node
      const date = new Date(release.publishedAt)
      // We have `loop: false`, so we return an object.
      // If we had `loop: true`, we would return an array of objects.
      return {
        VIDL_RELEASE_TAG: release.tagName,
        VIDL_RELEASE_URL: release.url,
        VIDL_RELEASE_WHEN: moment(release.publishedAt).fromNow(),
      }
    }
  }

Dev instructions

First, to get started:

1. Install Node.js
2. Run npm install
3. Go here to generate a GitHub personal access token with the read:user scope.
4. Create a .env file like this, with your token:

INPUT_TOKEN=mytoken
INPUT_TEMPLATE=EXAMPLE_TEMPLATE.md
INPUT_OUTPUT=EXAMPLE_OUTPUT.md

Now you can test the action by running the following command:

npm run test

Build:

npm run build

readme-template-action's Issues

How to get the repo name where the workflow is running?

Hello,

Thanks for this project, It is being very useful. I have encountered a new scenario that I am not sure how to handle:

Let's say I am running this workflow on a repository called X, how can I access the repo name X from the template file?

Thank you

Improvements for this action

While I like this action do I feel like it could receive some improvements to make it better to use.

1) Option to exclude forks

Placeholders such as {{ loop 3_NEWEST_REPOS }} include forks, which is something people like me would like to exclude.
So maybe have an option like a with action option to exclude forks from the lists.

2) Better options for loop size

I feel like only having 3_MOST_STARRED_REPOS, 3_NEWEST_REPOS and 3_RECENTLY_PUSHED_REPOS for the loop placeholder is fairly limiting on what you want to show. What if someone wants to display more or less than 3 repos?

While I get that there is the option of defining or overriding placeholders is it imo not an ideal solution for everyone to have.

So perhaps have the placeholders like {{ loop MOST_STARRED_REPOS size=3 }} to allow a more customizable size?

Error: Cannot read property 'split' of undefined

When running the WF I keep getting an error in the step Generate README.md:

Run probablykasper/readme-template-action@v1
template: TEMPLATE.md
output: README.md
User data
    - Fetching
    - Injecting
TypeError: Cannot read property 'split' of undefined
    at inject (/home/runner/work/_actions/probablykasper/readme-template-action/v1/dist/index.js:10961:15)
    at run (/home/runner/work/_actions/probablykasper/readme-template-action/v1/dist/index.js:10996:17)
    at processTicksAndRejections (internal/process/task_queues.js:93:5)
Error: Cannot read property 'split' of undefined

My wf.yml file is the same as the one you posted in your repo README file:

name: Readme Template Generator
on:
  workflow_dispatch:
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Generate README.md
        uses: probablykasper/readme-template-action@v1
        with:
          token: ${{ secrets.README_TEMPLATE_TOKEN }}
          template: TEMPLATE.md
          output: README.md
      - name: Update README.md
        run: |
          if [[ "$(git status --porcelain)" != "" ]]; then
            git config user.name "GitHub Action"
            git config user.email "[email protected]"
            git add .
            git commit -m "Auto-update README.md"
            git push
          fi

The only difference is that I will execute this WF manually instead of it being scheduled. What can I do to solve this issue?

Thank you