Tangled Sync#

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.

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.

Getting Started#

Configuration#

Before running any scripts, you need to configure the project. Create a src/.env file based on src/.env.example:

cp src/.env.example src/.env

Then edit src/.env with your actual values:

• BASE_DIR – the local directory where GitHub repositories will be cloned.
• GITHUB_USER – your GitHub username or organisation.
• ATPROTO_DID – your ATProto DID (Decentralized Identifier).
• BLUESKY_PDS – the URL of your Bluesky PDS instance.
• BLUESKY_USERNAME – your Bluesky username.
• BLUESKY_PASSWORD – your Bluesky password.

Make sure this file is properly set up before proceeding.

Installation#

1. Clone this repository locally.
2. Navigate to the project directory.
3. Run:

npm install

This will install all dependencies required for syncing GitHub repositories and interacting with ATProto.

Verify SSH Connection to Tangled#

• 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.

Without proper SSH authentication, repository creation and pushing will fail.

Testing AT Proto Connection#

Before running the full sync, test your AT Proto connection:

npm run test-atproto

This will:

• Verify your Bluesky credentials
• Confirm your DID matches the configuration
• List any existing sh.tangled.repo records
• Validate the connection to the PDS

Running the Sync Script#

Once configuration, SSH verification, and AT Proto testing are complete, run:

npm run sync

What happens during the sync:

1. Login to Bluesky: The script authenticates using your credentials to allow publishing ATProto records.
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).
3. Ensure Tangled Remotes: For each repository, a tangled remote is added if it doesn’t exist.
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.
5. Update README: Each repository’s README is updated to include a link to its Tangled mirror, if it isn’t already present.
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.

Notes & Best Practices#

• Directory Management: The script ensures that your BASE_DIR exists and creates it if necessary.
• Record Uniqueness: ATProto records use a time-based, sortable ID (TID) to ensure uniqueness. Duplicate IDs are avoided automatically.
• Error Handling: If a repository cannot be pushed to Tangled, the script logs a warning but continues processing the remaining repositories.
• Idempotency: Running the script multiple times is safe; existing remotes and ATProto records are checked before creation to prevent duplicates.

Example Workflow#

# Run the sync script
npm run sync

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.

This allows you to quickly confirm that all GitHub repositories have been mirrored and documented properly on Tangled.

Contribution & Development#

If you plan to contribute:

• Ensure Node.js v18+ and npm v9+ are installed.
• Test the script in a separate directory to avoid accidentally overwriting your production repositories.
• Use console.log statements to debug or track progress during development.
• Maintain proper .env configuration to avoid leaking credentials.

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.