Week 2: Workflowr Project Setup

This assignment is due by 2/4/2026 at 8am.

Overview

This assignment builds directly on the workflowr vignette: https://workflowr.github.io/workflowr/articles/wflow-01-getting-started.html. Your goal is to create a new workflowr project with a clean structure, publish at least one analysis file, and make it available as a GitHub Pages site.

I don’t expect that you necessarily use workflowr in the class or more generally, but I think it is useful to see how the package takes a structured approach to:

1. Setting up a predictable project structure
2. Uses Git to support version control and reproducibility
3. Allows you to publish your reports easily at GitHub Pages accessible to others.

Learning goals

• Initialize a workflowr project with a reproducible structure
• Knit analysis files with workflowr and track the build status
• Publish a workflowr site to GitHub Pages

Setup requirements

Before starting, make sure you have:

• R and RStudio installed
• Git installed and configured (For help, see: https://happygitwithr.com)
• A GitHub account
• The workflowr package installed

# Install once if needed
install.packages("workflowr")

Tasks

1. Start a new workflowr project

Create a new project named something like workflowr-<your-name> in a location you can find later. The wflow_start command will setup a new workflowr project in the speecified directory (by default, it does not overwrite existing projects).

library(workflowr) # load library
wflow_start("~/Downloads/workflowr-michael_28jan2026") # change to wherever your project will be

Open the project in RStudio (File > Open Project) and review the default folders: analysis/, data/, code/, output/, and docs/.

2. Create a new analysis file

Create a new analysis Rmarkdown file at analysis/01-getting-started.Rmd. You can use wflow_open if you wish, or just File > New File > R Markdown.

In the Rmd file, include the following:

• A short paragraph describing the project topic you plan to use this semester
• Add a small public domain data file to the data/ folder (e.g., a CSV from data.gov or another public domain source).
• One code chunk that reads your data file from data/ and prints a small summary (e.g., str() or summary())

Next, add this new analysis page to your site index so it appears on the rendered site. Open analysis/index.Rmd and add a link under the Analysis section. Use a relative link to the rendered HTML file:

- [Getting started](01-getting-started.html)

3. Build and check the site locally

Use workflowr to build the site and check its status.

# wflow_open("analysis/01-getting-started.Rmd")
wflow_build("analysis/01-getting-started.Rmd") # build only one script
wflow_build() # build the whole site
wflow_status() # check the build status

4. Publish and commit with workflowr

Before publishing your own analysis file, publish the default site pages once so they are tracked by Git and appear on your site (these files are created by wflow_start()):

wflow_publish(c("analysis/index.Rmd", "analysis/about.Rmd", "analysis/license.Rmd"),
              message = "Publish initial site pages")

Now publish the new analysis page using workflowr so it is tracked by Git.

wflow_publish("analysis/01-getting-started.Rmd", message = "update") # committing your work to the repository

5. Push to GitHub and enable GitHub Pages

After publishing (basically concretizing a change), connect the project to GitHub with your username:

Setup your Github repository using the wflow_use_github function. I chose the Oauth route when prompted, but either is fine.

wflow_use_github("michaelhallquist")

Create a Personal Access Token (PAT) for GitHub (required for pushing over HTTPS)

GitHub no longer accepts your GitHub account password for pushing over HTTPS. Instead, you will create a Personal Access Token (PAT) and use it in place of a password when wflow_git_push() asks.

1. Log into GitHub in your browser.
2. Go to Settings → Developer settings → Personal access tokens.
3. Choose Tokens (classic) (recommended). If you prefer Fine-grained tokens, choose that instead and follow the fine-grained settings below.
4. Classic token settings: check repo and workflow, and set an Expiration (e.g., 90 days).
5. Fine-grained token settings: give it a name (e.g., workflowr-week2) and set an Expiration (e.g., 30–90 days). Under Repository access, choose Only select repositories and select the workflowr repo. Under Repository permissions, add Actions, Contents, and Pages; for each one, set Access to Read and write in the right-hand dropdown.
6. Click Generate token and copy it somewhere safe. You will not be able to see it again.

Treat the PAT like a password: don’t share it and don’t paste it into files that you will commit to GitHub.

Push the code from your computer to GitHub

wflow_git_push(set_upstream = TRUE)

When prompted:

• Username: your GitHub username
• Password: paste your PAT (not your GitHub account password)

If wflow_git_push() fails or gives strange errors, see the Troubleshooting section below for a command-line fallback (you will still use your PAT when asked for a password).

In GitHub, enable Pages for the docs/ folder on the branch you pushed (often main, but sometimes master).

Guidance here: https://docs.github.com/en/pages/quickstart

After configured, this should look like the following:

After a few minutes of setting this, the top part of the GitHub Pages for the repo (https://github.com/<username>/<reponame>/settings/pages) should look something like this:

6. Verify the published site

Open your GitHub Pages site and confirm:

• The home page loads
• Your analysis page appears in the navigation
• The analysis page renders your text and code output

Deliverables

1. Provide the URL of your project site.
2. Short reflection (2-3 sentences) on what was straightforward vs. confusing, what you think may be helpful about this approach and/or what aspects you may adopt in your own workflows

Troubleshooting

Authentication setup (default: PAT over HTTPS)

GitHub no longer accepts account passwords for Git pushes over HTTPS. You must use either:

1. A Personal Access Token (PAT) over HTTPS (default for this assignment)
2. An SSH key (alternative; great if you plan to use GitHub often)

Both options are secure. Unless you already use SSH for GitHub, use the PAT option below.

Option A (default): Personal Access Token (PAT) over HTTPS

Step 1: Create a PAT in GitHub

1. Log into GitHub in your browser.
2. Go to Settings → Developer settings → Personal access tokens.
3. Choose Tokens (classic) (recommended). If you prefer Fine-grained tokens, choose that instead.
4. Classic token settings: check repo and workflow, and set an Expiration (e.g., 90 days).
5. Fine-grained token settings: give it a name and set an Expiration (e.g., 30–90 days). Repository access: choose Only select repositories and pick your workflowr repo. Repository permissions: add Actions, Contents, and Pages; for each one, set Access to Read and write in the right-hand dropdown.
6. Click Generate token and copy it. You will not see it again.

Step 2: Push from R with workflowr (preferred)

Run this from your R session:

wflow_git_push(set_upstream = TRUE)

When prompted: - Username: your GitHub username - Password: paste your PAT

If wflow_git_push() isn’t working (or gives confusing errors), try the command line instead:

git push -u origin main

If your default branch is master, replace main with master. If asked whether to save the credential, say Yes (recommended).

Option B (alternative): SSH key

Step 1: Generate an SSH key

ssh-keygen -t ed25519 -C "youremail@unc.edu"

Press Enter to accept the default file location. Add a passphrase if you want extra security.

Step 2: Add your key to the SSH agent

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Step 3: Add the public key to GitHub

cat ~/.ssh/id_ed25519.pub

Copy the output. Then in GitHub: Settings → SSH and GPG keys → New SSH key → paste the key → Add.

Step 4: Switch your repo remote to SSH

git remote set-url origin git@github.com:<username>/<reponame>.git

Step 5: Test and push

ssh -T git@github.com

Then push from R (preferred):

wflow_git_push(set_upstream = TRUE)

If that fails, push from the command line:

git push -u origin main

If your default branch is master, replace main with master.

Using PAT or SSH without the command line (workflowr only)

If you want to work entirely in R with workflowr (no terminal commands), you can still authenticate:

PAT (HTTPS): Run wflow_git_push() from R. When it asks for a password, paste your PAT.

If you want to avoid re-typing it each time, you can store the PAT in your .Renviron file as GITHUB_PAT, restart R, then push like this:

wflow_git_push(username = "<github-username>",
               password = Sys.getenv("GITHUB_PAT"))

SSH: Switch the remote to SSH using workflowr, then push:

wflow_git_remote(remote = "origin", user = "<username>", repo = "<reponame>",
                 protocol = "ssh", action = "set_url")
wflow_git_push()

If SSH fails with a message about SSH support, use HTTPS + PAT or the command line (git push) instead.

wflow_git_push() fails with a git2r::push() error

Some students see errors like:

Error in 'git2r_push': unexpected http status code: 400

This is usually an authentication problem (HTTPS + no password support). Two fixes:

1. Use GitHub’s Personal Access Token (PAT) when prompted for a password.
2. Or, bypass git2r entirely and push with the Git CLI (still using a PAT if you are on HTTPS):

git push -u origin master

If your default branch is main, replace master with main. If you don’t have Git installed, install it first (https://happygitwithr.com). If you want advice on the git2r error, search the git2r GitHub issues for “unexpected http status code 400”.

git2r::push() fails with HTTP 403 (but git push works)

If you are using a PAT and see:

Error in 'git2r_push': unexpected http status code: 403

It usually means the token you provided doesn’t have permission to push or git2r is not using the same stored credential that your Git command line is using.

Try these in order:

1. Double-check your PAT settings (it must have access to the repo and Contents: Read and write; if you used a fine-grained token, also include Actions and Pages).
2. Create a new PAT and try again (copy/paste carefully; no spaces).
3. Use the Git CLI for the first push and set the upstream branch once:

git push -u origin HEAD

After that, git push should work without needing -u again for that repo/branch.

My analysis file isn’t showing up on GitHub Pages

If the file exists in analysis/ but doesn’t appear on your GitHub Pages site, run this checklist:

1. Build it: Run wflow_build() (or wflow_publish() which builds + commits).
2. Publish it: If you only built it, run wflow_publish("analysis/your-file.Rmd").
3. Check status: Run wflow_status() and confirm the new HTML is tracked.
4. Push it: Push the latest commit to GitHub.
5. Pages source: In GitHub → Settings → Pages, confirm main + /docs.
6. Wait + refresh: Give it a few minutes, then hard refresh your browser.

Recommended workflow to avoid push problems

This workflow keeps you in R for the main steps (default: HTTPS + PAT):

1. Create your project with wflow_start().
2. Publish changes with wflow_publish().
3. Push with workflowr:

wflow_git_push(set_upstream = TRUE)

If wflow_git_push() isn’t working, use the Git CLI instead (still using your PAT or SSH):

git status
git push -u origin master

If you prefer SSH, set up an SSH key on GitHub first, then ensure your remote is SSH:

git remote -v
git remote set-url origin git@github.com:<username>/<reponame>.git