208 lines
4.5 KiB
Markdown
208 lines
4.5 KiB
Markdown
---
|
||
|
||
````markdown
|
||
# GitHub Contribution Heatmap Updater (Mirror & LFS)
|
||
|
||
This repository contains scripts to:
|
||
|
||
1. Mirror repositories from Gitea to GitHub.
|
||
2. Rewrite commit emails to your GitHub account for heatmap updates.
|
||
3. Handle large/LFS-based repositories that fail normal mirroring.
|
||
````
|
||
---
|
||
|
||
## Full Workflow
|
||
|
||
### Step 1: Mirror normal repositories from Gitea to GitHub
|
||
|
||
Run the main mirroring script to copy all normal repositories from your Gitea account to GitHub.
|
||
|
||
```bash
|
||
python gitea-github-mirror.py
|
||
````
|
||
|
||
**What it does:**
|
||
|
||
* Fetches all public repositories from Gitea.
|
||
* Creates corresponding repositories on GitHub (if they don’t already exist).
|
||
* Mirrors all branches and tags to GitHub.
|
||
|
||
> ⚠️ If some repositories fail during this step (typically large or LFS-based repos), they will be handled in later steps.
|
||
|
||
---
|
||
|
||
### Step 2: Update contribution graph for successfully mirrored repositories
|
||
|
||
After mirroring, update commits and push to GitHub to reflect contributions on your heatmap.
|
||
|
||
```bash
|
||
python mirror-contribution-graph.py
|
||
```
|
||
|
||
**Example:**
|
||
|
||
```bash
|
||
python mirror-contribution-graph.py
|
||
```
|
||
|
||
**What it does:**
|
||
|
||
1. Fetches the latest commits from the local mirrored repo.
|
||
2. Rewrites all commit author emails to your GitHub email.
|
||
3. Pushes all branches and tags to GitHub, updating your contribution heatmap.
|
||
|
||
> ⚠️ This step is for **normal (non-LFS) repositories**.
|
||
|
||
---
|
||
|
||
### Step 3: Push failed/LFS repositories
|
||
|
||
For repositories that failed in Step 1 (usually large/LFS-based), use the `lfs-push-repo.sh` script.
|
||
|
||
**Run:**
|
||
|
||
```bash
|
||
sh lfs-push-repo.sh <repo_name> <gitea_url> <github_url>
|
||
```
|
||
|
||
**Example:**
|
||
|
||
```bash
|
||
sh lfs-push-repo.sh solo-level-app-automation https://gitea.domain.com/user/project.git https://github.com/user/project.git
|
||
```
|
||
|
||
**Arguments:**
|
||
|
||
* `<repo_name>`: Repository name.
|
||
* `<gitea_url>`: Original repository URL on Gitea.
|
||
* `<github_url>`: GitHub repository URL already created by the mirroring script.
|
||
|
||
> ✅ This ensures LFS files and history are pushed to the GitHub repository created in Step 1.
|
||
|
||
---
|
||
|
||
### Step 4: Update contribution graph for LFS repositories
|
||
|
||
After pushing the LFS repository, rewrite commits to your GitHub email for the heatmap.
|
||
|
||
**Run:**
|
||
|
||
```bash
|
||
python mirror-lfs-contribution-graph.py <repo_name> <path_to_local_repo>
|
||
```
|
||
|
||
**Example:**
|
||
|
||
```bash
|
||
python mirror-lfs-contribution-graph.py solo-level-app-automation ./git_repo_project_files/solo-level-app-automation/
|
||
```
|
||
|
||
**What it does:**
|
||
|
||
1. Fetches the latest commits from the local LFS repo.
|
||
2. Rewrites all commit emails to your GitHub email.
|
||
3. Pushes all branches and tags to GitHub, updating your contribution heatmap.
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
Set GitHub credentials inside the Python scripts:
|
||
|
||
```python
|
||
GITHUB_USER = "<your GitHub username>"
|
||
GITHUB_EMAIL = "<your GitHub email associated with GitHub account>"
|
||
GITHUB_TOKEN = "<your GitHub personal access token (PAT)>"
|
||
```
|
||
|
||
* The PAT must have **repo permissions** to push commits.
|
||
|
||
---
|
||
|
||
## Logs
|
||
|
||
* Each run generates a timestamped log file.
|
||
|
||
* Example: `mirror_log_20251212_001638.log`
|
||
* Logs include:
|
||
|
||
* Repositories processed
|
||
* Commit rewriting info
|
||
* Push status
|
||
* Any errors
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
* Install `git-lfs`
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install git-lfs
|
||
git lfs install
|
||
```
|
||
|
||
* Install `git-filter-repo` for Python scripts:
|
||
|
||
```bash
|
||
pip install git-filter-repo
|
||
```
|
||
|
||
* Commits preserve timestamps but rewrite author emails.
|
||
* Pushing with `--mirror` overwrites remote branches/tags — **use carefully**.
|
||
|
||
---
|
||
|
||
## Example Directory Layout
|
||
|
||
```
|
||
project-root/
|
||
│
|
||
├─ gitea-github-mirror.py
|
||
├─ mirror-contribution-graph.py
|
||
├─ lfs-push-repo.sh
|
||
├─ mirror-lfs-contribution-graph.py
|
||
├─ gitea_repos/ # mirrored normal non bare repo's (non working dir)
|
||
│ ├─ repo1
|
||
│ ├─ repo2
|
||
│ └─ ...
|
||
└─ git_repo_project_files/ # LFS / working repos
|
||
├─ lfs-repo1
|
||
├─ lfs-repo2
|
||
└─ ...
|
||
```
|
||
|
||
---
|
||
|
||
## Summary of Execution Order
|
||
|
||
1. **Mirror normal repositories:**
|
||
|
||
```bash
|
||
python gitea-github-mirror.py
|
||
```
|
||
|
||
2. **Update contribution graph for mirrored normal repos:**
|
||
|
||
```bash
|
||
python mirror-contribution-graph.py
|
||
```
|
||
|
||
3. **Push failed/LFS repositories:**
|
||
|
||
```bash
|
||
sh lfs-push-repo.sh <repo_name> <gitea_url> <github_url>
|
||
```
|
||
|
||
4. **Update contribution graph for LFS repositories:**
|
||
|
||
```bash
|
||
python mirror-lfs-contribution-graph.py <repo_name> <path_to_local_repo>
|
||
```
|
||
|
||
> Following this order ensures **all normal and LFS-based repositories** are mirrored, commits rewritten, and contribution heatmap updated correctly.
|
||
|
||
|
||
|