feat: add remote Linux Gitea authentication flow
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
# Linux GCM Setup
|
||||
|
||||
Use this reference when Git runs on native Linux. This includes a Linux desktop controlled from Windows through RDP, VNC, or similar software. Use the Windows reference only when Git itself runs on Windows or WSL is intentionally using the Windows GCM executable.
|
||||
|
||||
## Identify the Session
|
||||
|
||||
Verify Git, GCM, the executable paths, and the configured helper:
|
||||
|
||||
```bash
|
||||
uname -s
|
||||
git --version
|
||||
git-credential-manager --version
|
||||
command -v git
|
||||
command -v git-credential-manager
|
||||
git config --show-origin --get-all credential.helper
|
||||
```
|
||||
|
||||
If the GCM version command succeeds, reuse that installation. Do not install or upgrade it during an ordinary repository update.
|
||||
|
||||
A visible remote desktop does not guarantee that an agent or background shell inherited the desktop session. Check without printing unrelated environment values:
|
||||
|
||||
```bash
|
||||
test -n "${DISPLAY:-}" || test -n "${WAYLAND_DISPLAY:-}"
|
||||
```
|
||||
|
||||
## Install When GCM Is Missing
|
||||
|
||||
Linux needs both GCM and an explicitly selected credential store. Use an official installation method appropriate for the distribution: the .NET global tool, a verified Debian package, or a verified release tarball. Run `git-credential-manager configure` afterward.
|
||||
|
||||
Do not download an unpinned executable from an unofficial source. Verify the release signature or checksum before installation. If the normal package needs administrator rights, ask the user to run the installation locally or use an official current-user method; never ask for an administrator password in chat.
|
||||
|
||||
On a Debian-based host without administrator access, a verified official `.deb` can be unpacked into the current user's directories. Inspect the package first and stop if its layout differs from `usr/local/share/gcm-core`:
|
||||
|
||||
```bash
|
||||
gcm_package="/absolute/path/to/verified-gcm.deb"
|
||||
gcm_unpack_dir=$(mktemp -d)
|
||||
gcm_install_dir="${XDG_DATA_HOME:-$HOME/.local/share}/gcm-core"
|
||||
gcm_bin_dir="$HOME/.local/bin"
|
||||
|
||||
dpkg-deb -c "$gcm_package"
|
||||
test ! -e "$gcm_install_dir"
|
||||
test ! -e "$gcm_bin_dir/git-credential-manager"
|
||||
test ! -L "$gcm_bin_dir/git-credential-manager"
|
||||
dpkg-deb -x "$gcm_package" "$gcm_unpack_dir"
|
||||
test -x "$gcm_unpack_dir/usr/local/share/gcm-core/git-credential-manager"
|
||||
install -d "$(dirname "$gcm_install_dir")" "$gcm_bin_dir"
|
||||
cp -a "$gcm_unpack_dir/usr/local/share/gcm-core" "$gcm_install_dir"
|
||||
ln -s "$gcm_install_dir/git-credential-manager" "$gcm_bin_dir/git-credential-manager"
|
||||
"$gcm_bin_dir/git-credential-manager" --version
|
||||
"$gcm_bin_dir/git-credential-manager" configure
|
||||
```
|
||||
|
||||
Use the full executable path until `$HOME/.local/bin` is available on `PATH`. If an install directory or link already exists, inspect it and repair only the known broken installation; do not overwrite it blindly.
|
||||
|
||||
## Choose a Credential Store
|
||||
|
||||
For a graphical Linux session with a working Secret Service collection:
|
||||
|
||||
```bash
|
||||
git config --global credential.credentialStore secretservice
|
||||
git-credential-manager configure
|
||||
```
|
||||
|
||||
Secret Service requires a graphical session to unlock its collection. If Git runs from an agent, background shell, or terminal without access to that graphical session, configure GCM's in-memory cache only in the target repository:
|
||||
|
||||
```bash
|
||||
git config --local credential.credentialStore cache
|
||||
git config --local credential.cacheOptions "--timeout 900"
|
||||
```
|
||||
|
||||
This keeps the PAT in memory for 15 minutes and leaves GCM as the Git credential helper. Do not replace it with a plaintext credential store. Do not change a working global Secret Service configuration merely because one repository is being updated from a non-graphical shell.
|
||||
|
||||
For persistent use without a graphical session, GCM also supports the `gpg` store after `gpg`, `pass`, and a key pair have been set up. Do not initialize those tools or keys as a side effect of a repository update unless the user requests it.
|
||||
|
||||
## OIDC Web Login and Git Push
|
||||
|
||||
An organization may use DingTalk or another OIDC provider for the Gitea website. Treat that as the way to open the account settings and create a PAT. Unless the Gitea instance explicitly documents another Git flow, the HTTPS push still uses:
|
||||
|
||||
- Username: the Gitea login accepted by the instance.
|
||||
- Password: a PAT with `write:repository`, entered only in the user's local terminal prompt.
|
||||
|
||||
Run the push from an interactive terminal:
|
||||
|
||||
```bash
|
||||
cd <prepared-repository>
|
||||
git push -u origin <target-branch>
|
||||
```
|
||||
|
||||
If the agent cannot expose an interactive prompt to the user, stop at this command and ask the user to run it. Resume with fetch and SHA verification after the user reports success. Never place the PAT in the remote URL, shell command, environment variable, chat, log, or repository file.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If GCM reports that `secretservice` cannot be used without a graphical interface, first confirm where the setting came from:
|
||||
|
||||
```bash
|
||||
git config --show-origin --get-all credential.credentialStore
|
||||
git config --show-origin --get-all credential.helper
|
||||
```
|
||||
|
||||
Then use the repository-local `cache` configuration above for this push, or rerun Git inside the real graphical session. Do not disable TLS verification. Install the organization's trusted CA correctly or stop and report the certificate issue.
|
||||
|
||||
Official references: [GCM installation](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/install.md), [credential stores](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/credstores.md), and [GCM configuration](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md).
|
||||
@@ -4,7 +4,7 @@ Read this reference for every Gitea repository update.
|
||||
|
||||
## 1. Resolve Inputs
|
||||
|
||||
Identify the clean Gitea HTTPS URL, prepared source paths, repository target paths, target branch, and commit intent. If a source-to-target mapping is ambiguous, stop and ask before writing.
|
||||
Identify the clean Gitea HTTPS URL, prepared source paths, repository target paths, target branch, commit intent, and the operating system where Git actually runs. If a Windows machine only displays or controls a remote Linux desktop, use the Linux flow. If a source-to-target mapping is ambiguous, stop and ask before writing.
|
||||
|
||||
## 2. Inspect Before Editing
|
||||
|
||||
@@ -12,7 +12,9 @@ Read applicable `AGENTS.md` and `CONTRIBUTING*`. Inspect the repository root, cu
|
||||
|
||||
Verify GCM using the active platform reference. A successful version command means reuse the existing installation without installing or upgrading it. Configure GCM only when its helper is absent or conflicting.
|
||||
|
||||
The user creates a Gitea PAT with `write:repository` and enters the Gitea login plus PAT only in the local GCM prompt. The account must already have repository write access.
|
||||
Web login and Git HTTPS authentication are separate concerns. For example, an organization may use DingTalk or another OIDC provider to sign in to the Gitea web interface, while Git HTTPS still expects a Gitea username and PAT. Do not assume that a browser login authorizes the command line unless the instance explicitly documents that behavior.
|
||||
|
||||
The user signs in to the Gitea web interface, creates a PAT with `write:repository`, and enters the Gitea login plus PAT only in the local GCM prompt. The account must already have repository write access. Never ask the user to paste a PAT into chat.
|
||||
|
||||
## 3. Choose the Repository Path
|
||||
|
||||
@@ -48,6 +50,8 @@ Confirm every staged path is in scope, deletions are intentional, no secret or t
|
||||
|
||||
Commit with an intent-based message. Re-fetch before pushing when the remote may have advanced. Push normally to the target branch. If the default branch is protected, push a task branch and report that review or merge is required. Do not use `--force`, `--force-with-lease`, `--no-verify`, or TLS bypasses.
|
||||
|
||||
When an interactive prompt is required but the agent cannot share it safely, give the user the exact working directory and `git push` command. The user enters the username and PAT in their own terminal. Do not replace this handoff with credentials in a command, URL, environment variable, or file. After the user reports that the push finished, continue with the remote verification below.
|
||||
|
||||
After a successful push, fetch the pushed branch and compare:
|
||||
|
||||
```bash
|
||||
@@ -60,4 +64,4 @@ Report completion only when the local and remote SHAs match. Include the reposit
|
||||
|
||||
## Stop Conditions
|
||||
|
||||
Stop on ambiguous paths, missing Git identity, authentication or TLS failure, insufficient account/PAT permissions, unexpected staged files, validation failure, overlapping user changes, non-fast-forward history requiring judgment, protected-branch rejection, server-hook rejection, or a request to overwrite remote history.
|
||||
Stop on ambiguous paths, missing Git identity, authentication or TLS failure, insufficient account/PAT permissions, unexpected staged files, validation failure, overlapping user changes, non-fast-forward history requiring judgment, protected-branch rejection, server-hook rejection, or a request to overwrite remote history. A required local credential prompt is a user handoff, not permission to weaken authentication or store the PAT insecurely.
|
||||
|
||||
Reference in New Issue
Block a user