Dynamically update GitHub profile README using GitHub Actions based on recent Activity

Preview

Recently, GitHub released a new feature that allows users to set a profile level README, allowing users to express themselves in more than just a one-line bio.

Create a profile level README

This can be done by creating a new repository with the same name as your username (case sensitive): https://github.com/new. For instance, in my case, theboi/theboi.

theboi/theboi

Next, add a README file — both README.md and README.rst work, but for this tutorial, I will use README.md. (A benefit of using .rst is that cells can span rows/columns; however, the syntax is different).

Customising your README

If you were to do a quick Google search, you should be able to find some really cool ones like:

And yes, the last 2 are powered by GitHub Actions.

Adding a GitHub Action Workflow

In the repository you just created, go to the Actions tab.

Actions tab

Click set up a workflow yourself.

GitHub will create a new .github directory for you, in which you will find your workflow/action files.

GitHub Workflows are written in YAML (YAML Ain’t Markup Language). If you are not familiar, here is a quick start.

Rename your file, I will call mine update-readme.yml. Now, let us go through the basic structure. There are 3 dictionaries (objects in JavaScript)— name, on and jobs.

First, name, pretty straightforward. Change the name to whatever you want.

Next, on. There are many events that can trigger workflows, such as push, pull_request, schedule, create, workflow_dispatch, the list goes on. The full list can be found on GitHub’s documentation. For today’s purpose, delete everything under on and replace it (ensure you indent properly):

on:
  schedule:
    - cron: "*/20 * * * *"

This tells the workflow to run every 20 mins using the cron syntax. You may use this to help if you want to set your own time.

Finally, jobs. A job is a set of tasks which run in steps. Different jobs can run concurrently. Learn more here. You may delete everything under steps and replace it:

- name: Update GitHub Profile README
  uses: theboi/github-update-readme@master
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    header: "Hey, I'm Ryan! 👋"
    subhead: "Currently a student in Singapore, passionate about creating all-things-tech to improve society."
    footer: "**Learn more about me at [ryanthe.com](https://www.ryanthe.com)!**"

(If the indenting here does not work, you can reference mine)

Breakdown:

• name: The name of the step
• uses: The GitHub Action (which I created) that we are using. Feel free to fork it (and hopefully PR) if you have some improvements for it.
• env: Sets the GITHUB_TOKEN environment variable so the GitHub Action is able to modify your README file.
• with: Sets other variables which you can find in the README of this repository.

Hit Start commit and Commit new file, optionally providing a title and description.

Lastly, add a DISPLAY.jpg to the root of each of your repositories, especially this username/username repository, to be shown in the table.

If a repository does not include a DISPLAY.jpg, the image displayed would default to the one used in username/username.

Now, wait 20 mins and see if it works.

Further customising the GitHub Action

There are a few more options you may customise such as customReadmeFile, reposPerRow or repoCount. You may find details on this in the README of github-update-readme.

You may also choose to fork the repository, in which case you can customise a lot more. Feel free to submit PRs or give suggestions on how I may enhance my GitHub Action.

Thanks for reading!