Git Credential Settings¶
These settings tune the second-factor git sessions used by Dev App Servers — the session lifetimes, the login UX, and the read-fallback toggle. They are global (platform-wide), set in Settings → Muppy → Git credentials (second factor).
For how tokens are resolved and how muppy-git-login is used on a box, see the
Git Tokens guide. This page is only about the tuning knobs.
The settings at a glance¶
| Setting | Param (ir.config_parameter) |
Default | What it controls |
|---|---|---|---|
| Write session lifetime | muppy_git.login_session_default_ttl_hours |
4 h | How long an approved read+write session stays valid before re-approval. The most sensitive window. |
| Read session lifetime | muppy_git.read_session_ttl_hours |
12 h | How long an approved read-only session stays valid. Lower risk → longer (≈ one approval per day). |
| Provisioning grant lifetime | muppy_git.provisioning_grant_ttl_minutes |
20 min | Window of the short, owner-approved read grant auto-used for the first clone when a box is provisioned. |
| Approval deadline (device code) | muppy_git.login_device_code_ttl_seconds |
600 s (10 min) | How long a pending login may be approved before it expires (RFC 8628 device code). Server-side. |
| Login poll interval | muppy_git.login_poll_interval_seconds |
4 s | How often muppy-git-login polls Muppy to see whether the approval came through. |
| Login wait timeout | muppy_git.login_helper_block_timeout_seconds |
180 s (3 min) | How long muppy-git-login keeps waiting for approval before giving up. Client-side. The credential helper itself never blocks. |
| Allow RW token for read | muppy_git.use_rw_token_for_read |
off | If a user has no read-only token, serve their read-write token for read sessions instead of refusing. Breaks least-privilege — leave off unless you accept the trade-off. |
The session lifetimes are defaults — a login can request its own duration
Write session lifetime and Read session lifetime are the durations used when
muppy-git-login is run without a duration. The command accepts an optional
duration to open a shorter (or longer) session for that login:
muppy-git-login <your-muppy-username> 5m # 5 minutes
muppy-git-login <your-muppy-username> 2h # 2 hours
muppy-git-login <your-muppy-username> 4 # a bare number = hours
The requested duration is honored as-is (there is no cap); omit it to fall back to the setting above.
The two timeouts — they are not the same thing¶
The single most confusing pair is Approval deadline (device code) and Login wait timeout. They sit on opposite ends of the login flow:
| Approval deadline (device code) | Login wait timeout | |
|---|---|---|
| Side | Server (Muppy) | Client (muppy-git-login on the box) |
| Default | 600 s (10 min) | 180 s (3 min) |
| Bounds | the human — how long you have to click Approve in Muppy before the request dies | the terminal — how long your shell stays blocked waiting |
| When it fires | the pending grant becomes expired and can no longer be approved |
the command stops polling, prints "timed out waiting for approval", and returns |
muppy-git-login calls Muppy to open a pending request, then polls every
poll interval seconds for up to the login wait timeout, watching for your
approval.
A timed-out login leaves you with no session — you must run it again
The login command writes the session to the box only when it sees the
approval during its wait window. If you approve after the Login wait
timeout has elapsed, the command has already given up and nothing is
written to the box. The pending request still sitting on the server is
not resumed — it simply expires at the Approval deadline. The next
git push will find no session and tell you to log in again.
There is no "the next git operation will pick up the approval". If the
wait timed out, re-run muppy-git-login (which opens a fresh request to
approve) and approve it while the command is waiting.
Keep the deadline ≥ the wait
The Approval deadline should stay greater than or equal to the Login wait timeout, so the pending request is approvable for at least as long as the client is willing to wait. With the defaults (10 min ≥ 3 min) there is comfortable headroom. If you raise the Login wait timeout, raise the Approval deadline to match. (Note: the extra minutes of server-side approvability beyond the client's wait are just slack — the box stops polling when the Login wait timeout elapses.)
What does persist: the approved session¶
Once a login is approved in time, the box stores the session and it stays
valid for its lifetime — Write session lifetime (4 h) or Read session
lifetime (12 h). For that whole window, every git operation just works with
no further approval: the credential helper resolves the token on demand on each
call, transparently. You only log in again when the session expires (or you
run muppy-git-logout).
So there are two different "persistences" — don't confuse them:
- Across git operations within an approved session → yes, automatic, until expiry.
- Across a login that timed out before approval → no; re-run
muppy-git-login.
Check the current session anytime on the box with muppy-git-status.
Choosing values¶
- Write session lifetime — shorter is safer (more frequent human gate on pushes), longer is more convenient. 4 h covers a working session without a mid-afternoon re-approval.
- Read session lifetime — read is lower risk, so the default is longer (≈ one approval per day).
- Login wait timeout — how patient the CLI is. Raise it if approvers are typically slow to react; remember to keep the Approval deadline ≥ it.
- Login poll interval — lower = snappier pickup after approval, at the cost of more requests. 4 s is a good balance.
- Allow RW token for read — keep off. Turning it on means a user with only a read-write token can open read sessions with it, which defeats least privilege. Prefer giving users a dedicated read-only token.