Skip to contents

Mergin Maps Integration

Source: vignettes/mergin.Rmd
mergin.Rmd

Overview

rfp wraps the mergin-client CLI for pushing, sharing, and syncing QGIS projects with Mergin Maps. Field crews collect data on mobile devices via the Mergin Maps app; rfp handles the office-side workflow.

Authentication

The mergin CLI reads credentials from environment variables. Set in ~/.Renviron:

MERGIN_USERNAME=your_username
MERGIN_PASSWORD=your_password

Or use a bearer token (from mergin login):

MERGIN_AUTH=Bearer your_token_here

rfp checks for these before any Mergin operation and errors with actionable instructions if neither is set.

Create a project

After building a project with rfp_project_create(), push it to Mergin:

library(rfp)

rfp_mergin_create(
  "newgraph/sern_peace_2026",
  "~/Projects/gis/sern_peace_2026"
)
#> ℹ Creating Mergin project: newgraph/sern_peace_2026
#> ✔ Mergin project created: newgraph/sern_peace_2026

Share with collaborators

Grant access to field crew members:

rfp_mergin_share("newgraph/sern_peace_2026", "field_tech_1", "writer")
rfp_mergin_share("newgraph/sern_peace_2026", "field_tech_2", "writer")
rfp_mergin_share("newgraph/sern_peace_2026", "supervisor_1", "reader")

Permissions: "reader", "writer", or "owner".

Check sync status

See what’s changed locally and on the server:

rfp_mergin_status("~/Projects/gis/sern_peace_2026")
#> ### Server changes:
#> ### Local changes:
#> >>> Added:
#> + new_layer.gpkg
#> >>> Modified:
#> M form_pscis.gpkg

Sync (pull + push)

Pull server changes (field data), then push local changes (updated layers):

version <- rfp_mergin_sync("~/Projects/gis/sern_peace_2026")
#> ℹ Pulling Mergin changes
#> ✔ Pulled changes
#> ℹ Pushing Mergin changes
#> ✔ Pushed (version v42)
cat("Synced to", version)

The version is parsed from .mergin/client-log.txt and returned invisibly.

Pull and push separately

For more control, call pull and push individually:

rfp_mergin_pull("~/Projects/gis/sern_peace_2026")
# ... review changes ...
version <- rfp_mergin_push("~/Projects/gis/sern_peace_2026")

Remove a project

Permanently delete a project from the Mergin server. Requires explicit confirmation to prevent accidental deletion:

rfp_mergin_remove("newgraph/test_project", confirm = TRUE)
#> ℹ Removing Mergin project: newgraph/test_project
#> ✔ Mergin project removed: newgraph/test_project

The local project directory is not touched.

Gotcha: close QGIS before syncing

When QGIS has a GeoPackage layer open, SQLite WAL mode creates sidecar files (*.gpkg-wal, *.gpkg-shm). These can cause conflicts during mergin pull or push because the diff engine can’t reconcile in-flight transactions.

Save and close the QGIS project before running rfp_mergin_sync().