How to automate your GitHub profile

I came across Chris Titus’ README and saw that it is automated and I was kinda surprised that we could even do that. So today I’m just gonna explain how it works and how you can do it too.

Markscribe

Markscribe is basically a markdown template engine which allows you to make a template and dynamically change the content of the final file using the template. A great example of this is HUGO; it has template files which is the theme you are using and then you can add your blogs or whatever you want in those template files. However with markscribe it will be all dynamic and you don’t have to edit everything yourself.

This is useful when making your README file on GitHub. For example, my GitHub profile has dynamic content like recent 3 posts, PRs & 3 things i’m currently working on. These 3 things change over time so I can use something like Markscribe to automate these changes depending on what I push on GitHub.

This sounds very confusing and advanced however its not that hard.

Init

First of all you need to create a README.gtpl, this will contain all the static content and defination of the dynamic content. For example, for my README, I copied all the contents of the normal README file into README.gtpl and then change the dynamic stuff like pull request section with dynamic links like so:

1
2
3
4

### 🔨 Recent Pull Requests
{{ range recentPullRequests 3 }}
- [{{ .Title }}]({{ .URL }}) on [{{ .Repo.Name }}]({{ .Repo.URL }})
{{- end }}

This will have the title of the PR in [ ] and then the url in ( ) then “on” and then the repository name and url just like the title and the url of the PR so an example output would be something like this:

• Add comments section on mansoorbarri/website

you can get more information about this dynamic links on markscribe’s wiki page or from someone’s readme file. Markscribe wiki: https://github.com/muesli/readme-scribe/ My readme file: https://github.com/mansoorbarri/MansoorBarri

GitHub Automation

to actually automate this process, you need to use GitHub workflows. For this,

• create this file in the following folders, these folders may not be there already so you might have to make them as well. File: /.github/workflows/main.yml
• then add the following code so it uses README-scribe and outputs a README file

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

name: markscribe

on:
  push:
  workflow_dispatch:
  schedule:
    - cron: "0 */1 * * *"

jobs:
  markscribe:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Generate README
        uses: muesli/readme-scribe@master
        env:
          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
        with:
          template: 'README.gtpl'
          writeTo: 'README.md'

      - name: Commit README
        uses: stefanzweifel/git-auto-commit-action@v4
        env:
          GITHUB_TOKEN: ${{ github.token }}
        with:
          commit_message: 'markscribe: update README.md'

Here you can see that you need a GitHub token, this can be generated by going to: account settings > developer settings > personal access tokens > Tokens (classic) > Generate new token > Generate new token (classic)

to be honest, don’t know why this is so hard and under soo many menus but I guess its Microsoft being Microsoft.

• from here, add a name for the token and tick the box next to “Workflow” and then click “generate token”
• Now it will show a token, copy that & go to your README repository > settings > secrets and variables > actions > New repository secret > paste the token under secret* and give this a name as well, I named it GH_PAT but you can name it anything.
• In your main.yaml file, add your secret like so

1

GITHUB_TOKEN: ${{ secrets.GH_PAT }} 

add your secret’s name instead of GH_PAT

Finally, go to actions > select the markscribe action from the left column > Run workflow > Run workflow & this should work.

If it doesn’t, you can comment down below or have a look at my README repository to see where you went wrong. Note that some variables might be different like the secret name or the commit message.

that’s it <3