GitHub Actions with R

name: title
class: left bottom hide-count

.talk-meta[
.talk-title[
# GitHub Actions with R

A basic introduction
]

.talk-author[
Travis Gerke, ScD<br>
.moffitt-gray[.small[.blue-medium[Moffitt Cancer Center ].blue[ :: ].blue-light[Health Informatics]]]
]

.talk-date.moffitt-gray[
June 19, 2020
]
]

.talk-logo[]

.title-image[]

<!-- Moffitt Logo and Slide Border ----

All slides except "title" and "inverse" slides
have the Moffitt Color Bar and logo.

Additional classes are provided to disable both:

- `class: no-logo` hides the logo
- `class: no-border` hides the border

or to force either to be shown

- `class: moffitt-slide-logo` shows the logo
- `class: moffitt-slide-border` shows the border
-->

---
### Some stuff you'll be able to do after this talk

* Automatically render a `.Rmd` file to `.pdf`, `.md`, `.docx`, and `.html` after every edit

* Have an R task automatically run at 9pm every day

* Make sure jobs work across Windows/Ubuntu/macOS without fiddling with VMs

* Other nerd stuff, win arguments about GitHub vs GitLab vs Bitbucket

.h-center.w-30[
![](img/robot.gif)
]

---
### Rendering a `.Rmd` to multiple formats

* Fact: the git learning curve is steep, so it won't always be possible to perform collaborative document editing "the right way"

* But you _can_ convince non-git collaborators to edit a document in a web browser (also a useful workflow for convenience, e.g. edits by phone)

.h-center.w-70[
![](img/browser-editing.png)
]

---
### Getting browser-based edits into the right format

* Browser editing is fine, but you/consumers need the resulting `.docx`/`.pdf`/`.html`

* Rendering a `.Rmd` typically requires firing up RStudio, 😢 your browser workflow

* But there's a way...

.h-center.w-30[
![](img/action.gif)
]

---
### GitHub Actions

* GitHub deploys a virtual machine(s) for your repository to run tasks that you specify

* A classic use-case is CI/CD to test software across different operating systems; we're going to work through some simpler tasks here

* Using GitHub Actions in 5 steps
  1. Create the instruction document in `.github/workflows/my_task.yaml`. 
  <br>.small.moffitt-gray[* Each step below is an edit to `my_task.yaml`]
  2. Specify when you want the action to run
  3. Tell GitHub where you'd like to run the job (Ubuntu, Windows, and/or macOS)
  4. Specify what prebuilt actions you'd like to run before your action
  5. Define your action
  
---
### Let's see one in _action_

--
.h-center.w-30[
![](img/dadjoke.gif)
]
--

* In [this repo](https://github.com/tgerke/rmd-with-ci), I'm going to edit `my_document.Rmd` in the browser, and we'll check back in later

* In the meantime, we'll go through each GitHub Actions development step in detail

---
### Step 1: Create the instruction document

* The easiest way to do this is to borrow a template

* My favorite method: choose one from [`r-lib/actions`](https://github.com/r-lib/actions/tree/master/examples)
  <br>.small.moffitt-gray[Initiate the file with `usethis::use_github_action("render-readme.yaml")` (or whichever of the action templates you choose)]
  
  * Can generate one from scratch, once you know the structure (later)
  
  * Many good starter workflows are provided from GitHub [here](https://github.com/actions/starter-workflows)

---
### Step 2: Specify when you want the action to run

* You will find this block at the top of your `yaml` file

```yaml
on:
  push:
    branches:
      - master
  pull_request:
    branches:
      - master
```

---
### Step 2a: Get more specific about when to run

* This now runs only when changes are pushed to a specific document

```yaml
on:
  push:
    paths:
      - my-document/my-document.Rmd
```

* You can also choose specific days/times for the run to recur
<br> .small.moffitt-gray[<sup>*</sup> Uses [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07), the below runs at 4:30am every Wednesday]

```yaml
on:
  schedule:
    - cron: "30 4 * * 3"
```

---
### Step 3: Specify how/where you'd like the job to run

* The next `jobs:` block in your `yaml` will have a `runs-on:` argument
  * Two examples: one on macOS only, the next on 3 separate VMs

```yaml
jobs:
  render:
    name: Render my document
    runs-on: macOS-latest
```

```yaml
    runs-on: ${{ matrix.config.os }}
    name: ${{ matrix.config.os }}
    strategy:
      matrix:
        config:
          - os: windows-latest
          - os: macOS-latest
          - os: ubuntu-16.04
```

---
### Step 4: Set up your environment with prebuilt actions

* These appear under the `uses:` tags
  * Common tasks: install R, pandoc, other software
  
```yaml
jobs:
  render:
    name: Render my document
    runs-on: macOS-latest
    steps:
      - uses: actions/checkout@v2
      - uses: r-lib/actions/setup-r@v1
      - uses: r-lib/actions/setup-pandoc@v1
      - uses: r-lib/actions/setup-tinytex@v1
```

---
### Step 5: Define your action

* Write these as shell scripts under `run:` tags
  * Can split named steps across several lines with `|`

```yaml
- name: Install rmarkdown
  run: Rscript -e 'install.packages("rmarkdown")'
- name: Render my document to all types
  run: Rscript -e 'rmarkdown::render("my-document/my-document.Rmd", output_format = "all")'
- name: Commit results
  run: |
    git add my-document/my-document*
    git commit -m 'Re-build my-document' || echo "No changes to commit"
    git push origin || echo "No changes to commit"
```

---
### The finished `.yaml` product

.h-center.w-70[
![](img/complete-yaml.png)
]

---
### Final thoughts

* Let's check in on [our document](https://github.com/tgerke/rmd-with-ci) which we modified earlier

* Some excellent resources for further learning
  * Jim Hester's [talk](https://www.jimhester.com/talk/2020-rsc-github-actions/) at rstudio::conf 2020
  * A [short online book](https://ropenscilabs.github.io/actions_sandbox/) from rOpenSciLabs
  * A list of [Awesome Actions](https://github.com/sdras/awesome-actions#awesome-actions---)
  * The [`ghactions` package](https://www.maxheld.de/ghactions/)

.footnote[
Slides: [https://tgerke.github.io/github-actions-with-r/](https://tgerke.github.io/github-actions-with-r/)
<br>
Slide source: [https://github.com/tgerke/github-actions-with-r](https://github.com/tgerke/github-actions-with-r)
<br><br>
<img src="img/twitter-brands.svg" alt="Twitter logo" width="24px"/> @travisgerke
]