Move from GitHub to Tangled
tombstone: moved to ewanc26/pkgs
+4
-119
+4
-119
README.md
+4
-119
README.md
···
1
-
# Tangled Sync
2
-
3
-
**Tangled Sync** is a TypeScript project that automates the process of syncing GitHub repositories to Tangled and publishing ATProto records for each repository. It is designed to streamline your workflow if you want your GitHub projects mirrored on Tangled while also maintaining structured metadata in ATProto.
4
-
5
-
This tool is particularly useful for developers and organisations that want a decentralized or alternative hosting layer for their code repositories while keeping them discoverable via ATProto.
6
-
7
-
---
8
-
9
-
## Getting Started
10
-
11
-
### Configuration
12
-
13
-
Before running any scripts, you need to configure the project. Create a `src/.env` file based on `src/.env.example`:
14
-
15
-
```bash
16
-
cp src/.env.example src/.env
17
-
```
18
-
19
-
Then edit `src/.env` with your actual values:
20
-
21
-
* `BASE_DIR` – the local directory where GitHub repositories will be cloned.
22
-
* `GITHUB_USER` – your GitHub username or organisation.
23
-
* `ATPROTO_DID` – your ATProto DID (Decentralized Identifier).
24
-
* `BLUESKY_PDS` – the URL of your Bluesky PDS instance.
25
-
* `BLUESKY_USERNAME` – your Bluesky username.
26
-
* `BLUESKY_PASSWORD` – your Bluesky password.
27
-
28
-
Make sure this file is properly set up before proceeding.
29
-
30
-
---
31
-
32
-
### Installation
33
-
34
-
1. Clone this repository locally.
35
-
2. Navigate to the project directory.
36
-
3. Run:
1
+
# tangled-sync — Archived
37
2
38
-
```bash
39
-
npm install
40
-
```
3
+
> **This repository has been tombstoned.** `@ewanc26/tangled-sync` has moved to the [`@ewanc26/pkgs`](https://github.com/ewanc26/pkgs/tree/main/packages/tangled-sync) monorepo.
41
4
42
-
This will install all dependencies required for syncing GitHub repositories and interacting with ATProto.
5
+
This repository is kept for historical reference only and will not receive further updates.
43
6
44
7
---
45
8
46
-
### Verify SSH Connection to Tangled
47
-
48
-
* If the Tangled remote does not exist for a repository, the script will attempt to create it on first run. This requires a working SSH key associated with your account.
49
-
50
-
Without proper SSH authentication, repository creation and pushing will fail.
51
-
52
-
---
53
-
54
-
### Testing AT Proto Connection
55
-
56
-
**Before running the full sync**, test your AT Proto connection:
57
-
58
-
```bash
59
-
npm run test-atproto
60
-
```
61
-
62
-
This will:
63
-
- Verify your Bluesky credentials
64
-
- Confirm your DID matches the configuration
65
-
- List any existing `sh.tangled.repo` records
66
-
- Validate the connection to the PDS
67
-
68
-
### Running the Sync Script
69
-
70
-
Once configuration, SSH verification, and AT Proto testing are complete, run:
71
-
72
-
```bash
73
-
npm run sync
74
-
```
75
-
76
-
What happens during the sync:
77
-
78
-
1. **Login to Bluesky:** The script authenticates using your credentials to allow publishing ATProto records.
79
-
2. **Clone GitHub Repositories:** All repositories under your configured GitHub user are cloned locally (excluding a repository with the same name as your username to avoid recursion).
80
-
3. **Ensure Tangled Remotes:** For each repository, a `tangled` remote is added if it doesn’t exist.
81
-
4. **Push to Tangled:** The script pushes the `main` branch to Tangled. If your `origin` remote’s push URL points to Tangled, it will reset it back to GitHub.
82
-
5. **Update README:** Each repository’s README is updated to include a link to its Tangled mirror, if it isn’t already present.
83
-
6. **Create ATProto Records:** Each repository gets a structured record published in ATProto under your DID, including metadata like description, creation date, and source URL.
84
-
85
-
---
86
-
87
-
### Notes & Best Practices
88
-
89
-
* **Directory Management:** The script ensures that your `BASE_DIR` exists and creates it if necessary.
90
-
* **Record Uniqueness:** ATProto records use a time-based, sortable ID (TID) to ensure uniqueness. Duplicate IDs are avoided automatically.
91
-
* **Error Handling:** If a repository cannot be pushed to Tangled, the script logs a warning but continues processing the remaining repositories.
92
-
* **Idempotency:** Running the script multiple times is safe; existing remotes and ATProto records are checked before creation to prevent duplicates.
93
-
94
-
---
95
-
96
-
### Example Workflow
97
-
98
-
```bash
99
-
# Run the sync script
100
-
npm run sync
101
-
```
102
-
103
-
After execution, you’ll see logs detailing which repositories were cloned, which remotes were added, which READMEs were updated, and which ATProto records were created.
104
-
105
-
This allows you to quickly confirm that all GitHub repositories have been mirrored and documented properly on Tangled.
106
-
107
-
---
108
-
109
-
### Contribution & Development
110
-
111
-
If you plan to contribute:
112
-
113
-
* Ensure Node.js v18+ and npm v9+ are installed.
114
-
* Test the script in a separate directory to avoid accidentally overwriting your production repositories.
115
-
* Use `console.log` statements to debug or track progress during development.
116
-
* Maintain proper `.env` configuration to avoid leaking credentials.
117
-
118
-
---
119
-
120
-
**Tangled Sync** bridges GitHub and Tangled efficiently, providing automatic mirroring, record management, and easy discoverability. Following these steps will ensure a smooth, automated workflow for syncing and publishing your repositories.
121
-
122
-
## ☕ Support
123
-
124
-
If you found this useful, consider [buying me a ko-fi](https://ko-fi.com/ewancroft)!
9
+
**New location:** [`https://github.com/ewanc26/pkgs/tree/main/packages/tangled-sync`](https://github.com/ewanc26/pkgs/tree/main/packages/tangled-sync)