Manage locks and roles

Admins can undo check-outs 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 Checked out by others.
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.

Locks belong to the GitHub account

A check-out (LFS lock) is held by the GitHub account that made it — not by the machine or the project. This matters when someone works under more than one account:

• Switching projects (same account) keeps your locks — GitM just shows a passive reminder of what's still checked out where.
• Switching GitHub accounts, or disconnecting, leaves your locks with the account you switched from; the new account cannot check those files in. GitM warns first (with the count) so you can check in before switching. If files are already stranded, switch back to that account to check them in, or an admin can Force Unlock them.

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 undoes the check-out; the file returns to Available 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.