Git Sync · Personal Access Token (PAT) Setup Guide

1. What is a Personal Access Token (PAT)

A PAT (Personal Access Token) is a secure credential provided by Git platforms such as GitHub, Gitee and GitLab. It replaces your account password for Git pull and push operations.

All major Git platforms have disabled direct password authentication for Git over HTTPS. You must use a PAT to pull and push your repository via HTTPS.

Key benefits of PAT

• Granular permissions: Grant only repository read/write access without exposing full account privileges
• Revocable: If your token is compromised, you can delete it separately without changing your account password
• Expiry date support for improved security
• Isolated access: Create a dedicated PAT exclusively for Leaf Note

Important: The PAT is shown only once after creation. You cannot view it again once you close the page. Copy and save it immediately.

2. General configuration rules (applies to all platforms)

Fill in the fields on Leaf Note Git Sync settings page following these rules:

• Repository URL: HTTPS repository address (SSH URLs are not supported)
• Username: Your Git platform account username
• Password / Token: Paste your generated PAT here

3. PAT creation guide for each platform

3.1 GitHub (Recommended for international users)

We recommend using Classic Personal Access Token for best compatibility.

Steps:

1. Sign in to GitHub, click your avatar in the top-right corner → Settings

2. Scroll down and open Developer settings → Personal access tokens → Tokens (classic)

3. Click Generate new token (classic)

4. Enter Note: Leaf Note Sync

5. Set Expiration (90 days or custom expiry is suggested)

6. Under Scope, check repo (required for full repository read and write access)

7. Scroll to the bottom and click Generate token

8. Copy your token starting with ghp_ and paste it into Leaf Note configuration

3.2 Gitee

Gitee names PAT as "Private Token". It works well for users with connections to mainland China.

Steps:

1. Log into your Gitee account, click avatar on top right → Settings

2. Select Security Settings → Private Tokens on the left menu

3. Click Generate new token

4. Description: Leaf Note Git Sync (custom label for easy identification)

5. Check permission: projects (read & write repository) (only this permission is required for note sync)

6. Submit, complete password or SMS verification to generate token

7. Copy the full token string immediately and fill it into Leaf Note

3.3 GitLab / JiHu GitLab

For self-hosted GitLab or official GitLab users.

Steps:

1. Log into GitLab, click your avatar in top-right → Edit profile

2. On the left menu: Access Tokens

3. Fill token name and expiry date

4. Check scopes: read_repository, write_repository (repository read and write permission)

5. Create token and copy it right away

4. Limitations & Important Notes

• HTTPS only: Git sync only accepts HTTPS repository addresses. PAT cannot be used with SSH repositories.
• Principle of least privilege: Enable only repository read/write permissions; avoid unnecessary scopes for safety.
• Token expiration: Sync will stop working after PAT expires. Generate a new token and update settings.
• Token leakage: If you suspect token leakage, delete the corresponding token on the Git platform. No password change required.
• Local storage: Your token is saved locally on your device only. Leaf Note will not upload your token to any remote server.

5. Troubleshooting common issues

• Authentication failed on sync: Verify full token copied, repo read/write permission enabled, repository URL is HTTPS format.
• Push failed: Check if token expired, confirm repository access rights, ensure no unpulled remote commits.
• Pull failed: Double-check your username and confirm the PAT has not been revoked manually.

6. Feature description

Git sync in Leaf Note is an advanced feature for technical users. Automatic sync can resolve simple single-file text conflicts. When multi-file conflicts, directory structure conflicts or binary attachment conflicts occur, sync will abort automatically. You need to repair conflicts manually with tools like VSCode or GitKraken.