-------------------------------
Calendar synchronisation setup
-------------------------------

The MEG lab uses a synchronization workflow to mirror bookings from the
Corelabs (Booked) portal to a Google Calendar. This lets researchers use Google
Calendar features such as appointment schedules to manage participant bookings
while automatically respecting the lab's availability.

Infrastructure overview
=======================

The synchronization has three main components:

1. **Python script**: :github-file:`scripts/sync-gcal.py` fetches the lab's ICS
   feed, parses events, and upserts them into Google Calendar via the Google
   Calendar API.
2. **Google Cloud project**: a service account with Editor access to the
   specific lab Google Calendar.
3. **GitHub Actions**: the workflow :github-file:`.github/workflows/sync-gcal.yml`
   runs every 5 minutes on a self-hosted Windows workstation.

Google Cloud Platform setup
===========================

To maintain or update the synchronization, you need access to the Google Cloud
project:

1. **Service account**: create a service account in the GCP console.
2. **API key**: generate a JSON key for the service account and store it
   securely.
3. **Calendar access**: share the target Google Calendar with the service
   account's email (found in the JSON key) with **Make changes to events**
   permission.

GitHub repository secrets
=========================

The following secrets must be configured in the GitHub repository
(Settings > Secrets and variables > Actions):

- ``GOOGLE_SA_JSON``: the entire content of the service account JSON key file.
- ``GOOGLE_CALENDAR_ID``: the ID of the target Google Calendar.
- ``BOOKED_ICS_URL``: the private iCal subscription URL from Corelabs.
- ``LOCAL_CONDA_PATH``: (optional) path to the ``conda`` executable on the
  self-hosted runner.
- ``LOCAL_CONDA_ENV_PATH``: (optional) path to the conda environment to use.

Self-hosted runner configuration
================================

The workflow is designed to run on a **Windows** runner (specifically the MEG
workstation) to avoid dependencies on cloud-hosted runners and to leverage
local environments.

Windows specific tips:

- The workflow uses ``pwsh`` (PowerShell Core) for robust command execution.
- Environment variables like ``CONDA_EXE`` and ``CONDA_ENV_PATH`` are used to
  invoke the correct Python environment without requiring a full ``conda init``
  in every run, which prevents path recursion limits.
- The service account JSON is created on the runner during each run using the
  ``GOOGLE_SA_JSON`` secret and deleted afterward.

Thank you for your contribution.