security

Security & the Safety Model

Non-destructive by design

URGithub never runs destructive Git operations. It will not reset, force-push (--force), rebase, or clean your working tree — under any trigger, ever.

flowchart LR
    A{Inspection} -->|SAFE| B[CONTINUE]
    A -->|UNSAFE| C[BLOCK]
    C --> D[REPORT]

Loading

The synchronize operation is deliberately conservative:

git fetch
git pull --ff-only      # fast-forward only
git commit              # only when the policy allows
git push

Authorization is checked separately from authentication — having a valid login does not mean a repository is pushable, and the two are verified independently.

GitHub authentication & permissions

URGithub authenticates through your GitHub CLI session — it does not store or use its own GitHub credentials.

• repo scope required. The registration check requires the repo scope on the authenticated gh token. Verify with gh auth status.
• Never place tokens in config files. Do not copy or manually put GitHub tokens, passwords, private keys, or cloud credentials into URGithub configuration files. URGithub uses the authenticated GitHub CLI session instead.
• Git identity ≠ GitHub credentials. The user.name / user.email you configure in Git are only the author identity used for commits — they are not your GitHub authentication.

Secret detection

Every file is scanned before anything is pushed. Secrets are matched two ways (both configured under security.*):

Filename patterns

.env*            *.pem            *.key
credentials.json secrets.json     *.p12

Content patterns (regex)

What it catches	Example pattern
Private keys	-----BEGIN [A-Z ]*PRIVATE KEY-----
GitHub tokens	gh[opsur]_[A-Za-z0-9]{20,}
AWS access keys	AKIA[0-9A-Z]{16}
Google API keys	AIza[0-9A-Za-z\-_]{35}
Slack tokens	xox[baprs]-[0-9A-Za-z\-]{10,}
Stripe live keys	sk_live_[0-9A-Za-z]{20,}
Generic API keys	sk-[A-Za-z0-9_\-]{24,}
Inline secrets	`(?i)(api_key

Files larger than security.max_scan_bytes (default 1 MB) are not fully scanned. Add exceptions via security.allow_files — globs excluded from both the filename check and the content check — when you are certain a match is a false positive.

File size limits

Setting	Default	Behavior
limits.warn_file_mb	50 MB	Warned in the report
limits.max_file_mb	100 MB	Blocks sync when block_on_oversize is on (default)

When a repository is not pushed

Synchronization stops and reports when any of these are detected. Each case is journaled and visible in report.html:

Result	What it means
blocked: secrets	Secret patterns detected — by filename and file content
blocked: oversize files	Files over the hard size limit
blocked: divergence	Local and remote histories diverged — never merged automatically
blocked: remote unreachable	Remote inaccessible
blocked: no push permission	Authorization failure — no permission to push
blocked: no remote configured	No origin remote
blocked: missing	Folder missing / not a git repo / quarantined
skipped	Dirty tree without commit_policy.auto_commit — never silently commits
failed	Fetch / git add / commit / push fails (journaled with the reason)

A blocked operation is an intentional safety result, not a bug. Do not bypass it — inspect report.html first. One bad repo never blocks the others.

The four safety rules

Rule	Why it exists
Rule 0 — No registration → no operations	Unregistered runs only show the setup wizard; nothing else runs
Rule 1 — No scan → no sync	The sync engine only touches repositories scanned in the same run
Rule 2 — Every run produces a report	Failures and blocks are always visible, never silent
Rule 3 — Trigger type does not matter	Scheduled and automatic runs use the same safe pipeline as manual ones

Deleted / renamed repository policy

URGithub will not act on a locally deleted repository without a confirmation chain:

• deleted_repo_policy.confirm_scans — 3 consecutive scans must flag it.
• deleted_repo_policy.confirm_days — 7 days must pass.
• deleted_repo_policy.require_remote_confirmation — the remote must confirm deletion.
• deleted_repo_policy.require_user_confirmation — you must explicitly confirm.

Recommendations

• Never commit credentials or secrets into any repository — block-on-secrets is the last line of defense. Never commit .env files, private keys, GitHub tokens, password files, cloud credentials, or API keys unless they are intentional test values with no security impact.
• Use the least-privilege GitHub token/permission set URGithub can work with — grant the GitHub account and tools only the permissions necessary for the repositories you intend to manage.
• Keep the runtime directory (urgithub\.urgithub) protected — it holds configuration, registry, and reports. Use normal operating-system permissions to restrict access.
• Review report.html for blocked operations before investigating further — investigate the reason instead of disabling the protection blindly.
• Rotate any secret that was ever pushed, even once.

Reporting a vulnerability

• Secret detection is on by default (security.block_on_secrets). Anything flagged is reported and never pushed.
• To report a vulnerability, open a private advisory on GitHub or email the maintainer.
• Do not post keys or secrets in issues. When reporting a problem, redact GitHub tokens, passwords, private keys, personal access tokens, and private repository contents before opening an issue.

Next: Report & Journal — everything the report and journal record.