bllgdrive

Shared Google Drive and Google Sheets authentication for Big Life Lab R projects.

Provides a three-tier authentication hierarchy that works the same way across all BLL repos:

1. Service account -- for CI/CD and automated scripts
2. Cached OAuth -- for team members with GDRIVE_EMAIL configured
3. Interactive login -- browser-based fallback

Installation

# Install from GitHub
remotes::install_github("Big-Life-Lab/bllgdrive")

# Or with renv (recommended for projects)
renv::install("Big-Life-Lab/bllgdrive")
renv::snapshot()

Quick start

library(bllgdrive)

# Authenticate with Google Drive
bll_drive_auth()

# Authenticate with Google Sheets
bll_sheets_auth()

# Check what's configured
bll_auth_status()

Setup

For team members (local development)

Add your Google Workspace email to ~/.Renviron:

GDRIVE_EMAIL=your.name@biglifelab.org

Restart R after editing. On first use, bll_drive_auth() will open a browser window to authorise access. The token is cached in .secrets/ for subsequent sessions.

For CI/CD (GitHub Actions)

Store the service account JSON as a GitHub secret named GOOGLE_SA_KEY_JSON. The package detects this automatically:

- name: Download data from Google Drive
  env:
    GOOGLE_SA_KEY_JSON: ${{ secrets.GOOGLE_SA_KEY_JSON }}
  run: |
    Rscript -e '
      library(bllgdrive)
      bll_drive_auth()
      # ... your download code
    '

For organisation-wide access, set GOOGLE_SA_KEY_JSON as an organisation secret scoped to the repos that need it.

For automated local scripts

Place the service account JSON at .secrets/google-service-account.json in your project directory (already gitignored in most BLL repos), or set an explicit path:

GOOGLE_SA_KEY_PATH=/path/to/service-account.json

Service account resolution order

The package checks for a service account key in this order:

1. GOOGLE_SA_KEY_PATH environment variable (explicit file path)
2. .secrets/google-service-account.json (conventional project path)
3. GOOGLE_SA_KEY_JSON environment variable (inline JSON content for CI)

If none are found, falls back to OAuth (via GDRIVE_EMAIL or interactive).

Setting up a Google Cloud service account

These are one-time steps for the team administrator.

1. Go to Google Cloud Console
2. Create a project (e.g., big-life-lab-gdrive)
3. Enable the Google Drive API and Google Sheets API
4. Go to IAM & Admin > Service Accounts and create a new service account
5. Create a JSON key and download it
6. Share the relevant Google Drive folders or shared drives with the service account's email address (e.g., bll-gdrive@big-life-lab-gdrive.iam.gserviceaccount.com)
7. Distribute the key securely to team members and add it as a GitHub org secret

Using with renv

After installing with renv::install() and renv::snapshot(), the package is pinned in your lockfile. To update:

renv::install("Big-Life-Lab/bllgdrive")
renv::snapshot()

If your project has a DESCRIPTION with a Remotes field:

Remotes:
    Big-Life-Lab/bllgdrive

Environment variables

Variable	Purpose	Where to set
GDRIVE_EMAIL	Email for cached OAuth	~/.Renviron
GOOGLE_SA_KEY_PATH	Path to service account JSON	~/.Renviron or CI env
GOOGLE_SA_KEY_JSON	Inline service account JSON	GitHub secret (CI only)

Licence

MIT