setting up GitHub actions

automate your literature recommendation automation tool

Okay, hopefully you're interested in using refy by now, but you don't really want to have to manually run it in python once or twice a week. If the point of refy is to automate papers recommendation, automate refy too!

I assume that you're fairly familiar with GitHub here and know how to create and edit GitHub repositories. If not, please get in touch and I'll try to help with more details.

The easiest way is to use GitHub Actions to have refy update a GitHub repository for you. If you're repository's published to a GitHub Pages website, refy can even update your website for you! If everything works correctly, you'll have a GH action running periodically and updating your repository with the latest freshest preprints.

Currently the best way I've found to do this is is to let the GH action update my website. Maybe someone has a way to have actions email content to users instead, that'd be great. Get in touch if you know how to improve this workflow!

These are the steps to setup refy on GH Actions:

1. In your GH repository, save a library.bib file with your papers metadata and create a folder called scripts

2. In your scripts folder, create run_refy.py The content of run_refy.py should be:

import refy
from loguru import logger
from pathlib import Path
import sys

# setup logging
logger.remove()
logger.add(sys.stdout, level='DEBUG')
logger.add('log.log')

# create a HTML file with recomended papers
logger.info('Creating refy.html')
refy.Recomender(
 'library.bib',            # path to your .bib file
  n_days=7,               # fetch preprints from the last N days
  N=50,                    # number of recomended papers 
  show_html = False,
  html_path='./refy.html',
)

when your GH action runs, it will execute run_refy.py and this will create a refy.html file with your recommendations.

3. Create a new GitHub Actions workflow. From your repository's page, select Actions

from there, on the top left click onNew Workflow and in the next page select Simple Workflow (click on 'setup this workflow'). This will take you to a new page where you can edit your action's yaml workflow file. Delete all precompiled content and replace it with:

name: refy

on: 
  push:
  schedule:
    - cron: "0 6 * * 1,3,5" # Every Mon, Wed, Fri at at 6 AM UTC

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2 
      
      - name: checkout repo content
        uses: actions/checkout@v2 # checkout the repository content to github runner.
      
      - name: setup python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8 #install the python needed
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install git+https://github.com/FedeClaudi/refy.git          
          
      - name: execute py script # run the run.py to get the latest data
        run: |
          python scripts/run_refy.py
    
      - name: Commit refy.html
        run: |
          git config --global user.name 'auto-update'
          git config --global user.email '[e-mail]'
          git add "."
          git commit -am "updating refs"
          git push

Make sure to replace YOURUSERNAME at row 35 with your GitHub username.

You can read more about the workflow file syntax on the documentation, but this is the essence of what's happening.

on: 
  push:
  schedule:
    - cron: "0 6 * * 1,3,5" # Every Mon, Wed, Fri at at 6 AM UTC

this bit specifies when your GitHub action should run. Currently it runs on push, i.e. when you push a commit to your repository and on schedule. GH actions allows you to use cron syntax to schedule jobs that should run periodically. You can use this to have your action run as frequently as you'd like, I have it such that it updates my website three times a week.

Having the action running on push can be useful. If you have other applications that push content to the same repository, these can trigger a website update for you. I use paperpile as reference manager, and it has an option to automatically push a library.bib file to a GitHub repository every time I add papers to my collection. So whenever I add new papers, the .bib file in my repository is update and this triggers new papers recommendation 😍

Next, this:

      - name: setup python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8 #install the python needed
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install git+https://github.com/FedeClaudi/refy.git          
          

setups a python environment on the action's virtual machine and it fetches the latest refy code from its GH repository.

Then, the python script we created above is ran by:

      - name: execute py script # run the run.py to get the latest data
        run: |
          python scripts/run_refy.py

as we saw, this updates a refy.html file in your repository, so the next step is to commit this new version to your repository:

      - name: Commit refy.html
        run: |
          git config --global user.name 'auto-update'
          git config --global user.email '[e-mail]'
          git add "."
          git commit -am "updating refs"
          git push

job done, enjoy the new reads 🎉