Skip to content

docs: explain git identity and credentials in shared workspaces - #31152

Merged
nickvigilante merged 2 commits into
mainfrom
vigilante/eng-3444-docs-explain-git-identity-and-credentials-in-shared
Nov 3, 2026
Merged

nickvigilante merged 2 commits into
mainfrom
vigilante/eng-3444-docs-explain-git-identity-and-credentials-in-shared

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Adds a Git identity and credentials section to the shared workspaces guide and links it from the persistent shared workspaces tutorial.
Every user of a shared workspace uses the owner's Git identity, Git SSH key, external auth tokens, and user secrets, and the docs didn't say so.

Closes #30278.
Refs ENG-3444.

Changes

  • docs/user-guides/shared-workspaces.md: new section that covers what resolves to the owner, the security implications, the service account recommendation, and how a shared user commits and pushes as themselves, with trade-offs.
  • docs/tutorials/persistent-shared-workspaces.md: two sentences after the service account step that link to the new section.

Where this differs from the issue

  • The issue suggests git -c user.name=... -c user.email=....
    It has no effect when the template sets GIT_AUTHOR_* and GIT_COMMITTER_*, because Git env vars beat all config, including -c.
    The docs say this and recommend exporting the env vars or using git commit --author instead.
  • Service accounts have no email address and can't sign in to the dashboard, so the docs don't claim the Git provider attributes activity to the service account.
    The docs say what commits look like and suggest putting the service account's coder publickey on a dedicated machine account.
  • Added user secrets to the list of owner-scoped things, since docs/user-guides/user-secrets.md already warns about this.

Testing

  • Code sources: coderd/gitsshkey.go (GetGitSSHKey(ctx, workspace.OwnerID)), coderd/workspaceagents.go (external auth links looked up by workspace.OwnerID), agent/agent.go (GIT_SSH_COMMAND, env precedence), cli/agent.go (GIT_ASKPASS), cli/ssh.go (--forward-agent), examples/templates/docker/main.tf.
  • Ran with Git 2.53.0: exported GIT_* vars beat git -c user.*, --author changes only the author, and an empty GIT_AUTHOR_EMAIL produces name <>.
  • markdownlint-cli2, make lint/emdash, and Vale pass on both files.
    The pre-commit hook passed.
Not verified end to end (please check)
  • I didn't test SSH agent forwarding (coder ssh --forward-agent plus export GIT_SSH_COMMAND=ssh) against a real Git provider from a shared workspace.
  • I didn't run gh auth setup-git taking priority over Coder's GIT_ASKPASS in a workspace.
    This is based on Git's documented credential order: helpers first, then askpass.
  • I didn't check in a running deployment that coder publickey works with a service account token.

Generated by Coder Agents on behalf of @nickvigilante.

Shared users connect with the workspace owner's Git identity, Git SSH
key, external auth tokens, and user secrets. The shared workspaces guide
didn't say so, so owners sharing a personal workspace may not realize
shared users can push with their source control permissions.

Refs ENG-3444, closes #30278.
@linear-code

linear-code Bot commented Oct 21, 2026

Copy link
Copy Markdown

ENG-3444

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:53
@coder
coder Bot requested a review from matifali November 2, 2026 19:23
Comment thread docs/user-guides/shared-workspaces.md Resolved
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

@matifali re: your comment on automatic Git identity: agreed, that would be a better experience. Tracking it in #31706 so this PR can stay docs-only.

One wrinkle: shared users run as the same OS user, so per-user external auth tokens would need isolation to avoid leaking one user's token to the others.

Generated by Coder Agents on behalf of @nickvigilante.

@nickvigilante
nickvigilante merged commit 731f0c6 into main Nov 3, 2026
30 checks passed
@nickvigilante
nickvigilante deleted the vigilante/eng-3444-docs-explain-git-identity-and-credentials-in-shared branch November 3, 2026 18:26
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 3, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: explain git identity and credentials in shared workspaces

2 participants