> For the complete documentation index, see [llms.txt](https://federicoclaudi.gitbook.io/refy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://federicoclaudi.gitbook.io/refy/user-guide/setting-up-github-actions.md).

# setting up GitHub actions

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!

{% hint style="warning" %}
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 ](https://twitter.com/home)and I'll try to help with more details. 
{% endhint %}

The easiest way is to use [**GitHub Actions**](https://docs.github.com/en/actions) to have **refy** update a GitHub repository for you. If you're repository's published to a [**GitHub Pages website**](https://pages.github.com/), **refy** can even update [your website ](https://fedeclaudi.github.io/refy.html)for you!  If everything works correctly, you'll have a GH action [running periodically](https://github.com/FedeClaudi/FedeClaudi.github.io/actions/workflows/main.yml) and updating your repository with the latest freshest preprints. 

{% hint style="info" %}
Currently the best way I've found to do this is is to let the GH action update [my website](https://fedeclaudi.github.io/refy.html). Maybe someone has a way to have actions email content to users instead, that'd be great. Get [in touch](https://twitter.com/home) if you know how to improve this workflow!
{% endhint %}

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:

```python
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

![](/files/-MgNHVChQIcD9sAL36lA)

from there, on the top left click on`New 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:

```yaml
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 'YOURUSERNAME@users.noreply.github.com'
          git add "."
          git commit -am "updating refs"
          git push
```

{% hint style="warning" %}
Make sure to replace `YOURUSERNAME` at row `35` with your GitHub username.
{% endhint %}

You can read more about the workflow file syntax on the [documentation](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions), but this is the essence of what's happening. 

```yaml
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](https://en.wikipedia.org/wiki/Cron) 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.

{% hint style="info" %}
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**](https://paperpile.com/) 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 :heart\_eyes: 
{% endhint %}

Next, this:

```yaml
      - 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](https://github.com/FedeClaudi/refy).

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

```yaml
      - 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:

```yaml
      - name: Commit refy.html
        run: |
          git config --global user.name 'auto-update'
          git config --global user.email 'YOURUSERNAME@users.noreply.github.com'
          git add "."
          git commit -am "updating refs"
          git push
```

job done, enjoy the new reads :tada: