index.Rmd

---
title: "GitHub Actions with R"
subtitle: "A basic introduction"
author:
  - Travis Gerke, ScD
institute: ".small[.blue-medium[Moffitt Cancer Center ].blue[ :: ].blue-light[Health Informatics]]"
date: 'June 19, 2020'
output:
  xaringan::moon_reader:
    lib_dir: libs
    css: [moffitt-xaringan.css, moffitt-xaringan-extra.css]
    seal: false
    nature:
      titleSlideClass: ["bottom", "left"]
      slideNumberFormat: "%current%"
      highlightStyle: atom-one-light
      highlightLanguage: [r, yaml]
      highlightLines: true
      ratio: 16:9
      countIncrementalSlides: true
---

```{r setup, include=FALSE}
options(htmltools.dir.version = FALSE)
knitr::opts_chunk$set(
  fig.width=9, fig.height=3.5, fig.retina=3,
  out.width = "100%",
  cache = FALSE,
  echo = TRUE,
  message = FALSE, 
  warning = FALSE, 
  hiline = TRUE
)
```

name: title
class: left bottom hide-count

<!-- Title Slide -->

<!-- <div class="talk-logo"></div> -->

.talk-meta[
.talk-title[
# `r rmarkdown::metadata$title`

`r rmarkdown::metadata$subtitle`
]

.talk-author[
`r paste(rmarkdown::metadata$author, collapse = " &middot; ")`<br>
.moffitt-gray[`r paste(rmarkdown::metadata$institute, collapse = ", ")`]
]

.talk-date.moffitt-gray[
`r knitr::knit(text = rmarkdown::metadata$date)`
]
]

.talk-logo[]

.title-image[]

```{css echo=FALSE}
/* Define title slide image or logo here */
.talk-logo {
  width: 250px;
  height: 250px;
  position: absolute;
  bottom: 3%;
  right: 2%;
  background-image: url('img/hex-wall.png');
  background-size: contain;
  background-repeat: no-repeat;
  background-position: contain;
}
```

<!-- 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
]

```{css, echo=FALSE}
.title-image {
  width: 150px;
  height: 150px;
  position: absolute;
  top: 3%;
  left: 2%;
  background-image: url('img/ghactions.png');
  background-size: contain;
  background-repeat: no-repeat;
  background-position: contain;
}
.h-center {
  margin: 0 auto;
}
.v-center {
  display: flex;
  justify-content: center;
  align-items: center;
}
.w-30 {
  width: 30%;
}
.w-70 {
  width: 70%;
}
```