Circulate via GitHub Actions — circulate_via

Writes .github/workflows/deploy-webr.yml, a GitHub Actions workflow that builds the collection with the webrarian release that generated it and deploys the site to GitHub Pages.

Usage

circulate_via_github(path = ".", overwrite = FALSE)

Arguments

path: The collection, or any directory inside it.
overwrite: If TRUE, replace an existing workflow file. Without it, an existing file is an error and is left as it is.

Value

Invisibly, a character vector of every path written, which here is the workflow file.

Details

The workflow does four things:

Runs on pushes to main/master, pull requests and manual dispatch
Installs the webrarian release that generated it, then runs bind() (local and GitHub packages compile in Docker, which the runner has)
Caches webrarian's downloads between runs
Deploys to GitHub Pages from a separate job that alone may write to Pages, and never for pull requests

GitHub runs only the workflows at the root of a repository, so the file goes in .github/workflows/ there, even when the collection is in a subdirectory. The workflow then runs its steps in the collection's directory. Outside a git repository it is written in the collection, to be moved to the repository root once there is one.

After running this function, push the workflow and set the repository's Pages source to "GitHub Actions".

Examples

collection <- file.path(tempdir(), "webrarian-github-demo")
catalog(collection)
#> ✔ Created directory /tmp/RtmpQU25pJ/webrarian-github-demo
#> ✔ Created _webrarian.yml
#> ✔ Added "_site/" and ".webrarian/" to .gitignore
#> ✔ Cataloged webrarian collection: "webrarian-github-demo"
#> 
#> Next steps:
#>   Move into the collection: `setwd("/tmp/RtmpQU25pJ/webrarian-github-demo")`
#>   Acquire packages: `webrarian::acquire_package("dplyr")`
#>   Acquire files: `webrarian::acquire_file("data/")`
#>   Bind: `webrarian::bind()`
#>   Reading room: `webrarian::reading_room()`
#> ℹ Or pass `path` to each call, e.g. `webrarian::bind(path =
#>   "/tmp/RtmpQU25pJ/webrarian-github-demo")`

circulate_via_github(collection)
#> ! /tmp/RtmpQU25pJ/webrarian-github-demo is not in a git repository, so the workflow is written there. Move .github/workflows/ to the repository root when you create one.
#> ✔ Created /tmp/RtmpQU25pJ/webrarian-github-demo/.github/workflows/deploy-webr.yml
#> 
#> Next steps:
#>   Commit and push the workflow file
#>   In the repository's Settings > Pages, set Source to "GitHub Actions"
#> ℹ GitHub Pages cannot set response headers, so the site runs without
#>   cross-origin isolation there: Ctrl+C cannot interrupt R.

# Re-running requires an explicit overwrite
circulate_via_github(collection, overwrite = TRUE)
#> ! /tmp/RtmpQU25pJ/webrarian-github-demo is not in a git repository, so the workflow is written there. Move .github/workflows/ to the repository root when you create one.
#> ✔ Created /tmp/RtmpQU25pJ/webrarian-github-demo/.github/workflows/deploy-webr.yml
#> 
#> Next steps:
#>   Commit and push the workflow file
#>   In the repository's Settings > Pages, set Source to "GitHub Actions"
#> ℹ GitHub Pages cannot set response headers, so the site runs without
#>   cross-origin isolation there: Ctrl+C cannot interrupt R.

unlink(collection, recursive = TRUE)