Skip to content

Manage locks and roles

Admins can release locks that others hold, freeze files against editing, and define roles through .gitm.json.

Roles

Roles are defined in the repository's .gitm.json and reference GitHub team membership, for example:

"roles": {
  "admin": ["@org/cad-leads"],
  "contributor": ["@org/cad-members"],
  "reader": ["@org/everyone"]
}

In practice, GitM treats a user with GitHub Maintain or Admin permission on the repository as a GitM admin/manager. Admin-gated actions (force-unlock, the part-number toggle, deleting published files) check this permission.

Force-unlock a file

When a teammate holds a lock and is unreachable, an admin can release it.

Prerequisites

  • Admin/Manager permission on the repository.

Steps

  1. In the Files tab, find the file showing Locked by Other.
  2. Right-click → Force Unlock (admin only).
  3. Confirm the warning.

Warning: force-unlocking can discard the other person's unpublished work. They lose anything they checked out but never checked in. Use it only when they truly can't release it themselves, and tell them.

Freeze a file

Freezing marks a file as not to be changed (for example a released design). Frozen files are recorded in .gitm/frozen.json.

  • Freeze/unfreeze from the file's context menu (admin-gated).
  • The Team tab surfaces locks and activity for the repository.

Mark a milestone

A snapshot can be flagged as a milestone (recorded in .gitm/milestones.json) to mark a significant point in history, visible on the Snapshots tab and to GitMCloud.

Expected result

  • Force-unlock releases the lock; the file returns to Not Locked for everyone.
  • Frozen files are protected from casual edits and flagged in the UI.

Troubleshooting

Symptom Cause Fix
No Force Unlock option You're not Admin/Manager. Only admins see it.
Force-unlock didn't reach the server LFS lock server unreachable. Check connection; retry.
Deleting a published file is blocked Deleting published files needs Admin/Manager. An admin must do it.

Known limitations

  • Roles in .gitm.json are advisory and point at GitHub teams; the hard gate is the user's GitHub repository permission.
  • There's no audit log inside GitM beyond Git history and the .gitm/ records; use GitHub for a full audit trail.