mirror your GitHub repos to tangled.org automatically
docs: update README
author
Daniel Roe
date
(Jun 11, 2026, 11:35 PM +0100)
commit
3670623c
3670623c24164cf66ab2c9838c2ae89cfcb19893
parent
a03182e6
a03182e6927e5af9f707063b9a8580c432033ded
+64
-26
+64
-26
README.md
+64
-26
README.md
···
4
4
5
5
- [👉 Check it out](https://synchub.to/)
6
6
7
+
Install the GitHub App, connect your tangled identity, and every commit,
8
+
branch, and tag will be mirrored to tangled. No additional configuration required.
9
+
7
10
## Features
8
11
9
-
- a GitHub App
10
-
- OAuth connection to tangled
12
+
- no workflow file required
13
+
- one-time OAuth connection to tangled
11
14
- per-push sync of branches and tags
15
+
- a dashboard where you can resync, pause, or rotate keys
12
16
13
17
> [!IMPORTANT]
14
18
> Only public repositories are synced (tangled does not yet support private repositories).
15
19
16
-
## Try it out locally
20
+
## Run it locally
17
21
18
-
You will need:
22
+
You will need [Node 24+](https://nodejs.org), [pnpm 10+](https://pnpm.io)
23
+
(`corepack enable`), a [Neon](https://neon.tech) database (free tier is fine),
24
+
and the [Smee CLI](https://smee.io) for webhook proxying
25
+
(`pnpm add -g smee-client`).
19
26
20
-
1. A GitHub App with a webhook pointed at your local tunnel and `contents:read`, `metadata:read` permissions plus the `push`, `create`, `delete`, `repository` events.
21
-
2. A [Neon](https://neon.tech) Postgres database.
22
-
3. An AT Protocol confidential OAuth client (see `.well-known/atproto-client-metadata.json`).
27
+
```bash
28
+
corepack enable
29
+
pnpm install
30
+
cp .env.example .env # fill in the values, see below
31
+
pnpm db:migrate
32
+
pnpm dev
33
+
```
23
34
24
-
Set your environment variables in a `.env` file:
35
+
`.env.example` documents every variable. Generate the secrets with the bundled
36
+
helpers:
25
37
26
-
```env
27
-
NUXT_GITHUB_APP_ID=<github app id>
28
-
NUXT_GITHUB_APP_PRIVATE_KEY=<github app private key, pem>
29
-
NUXT_GITHUB_WEBHOOK_SECRET=<github app webhook secret>
30
-
NUXT_DATABASE_URL=<neon postgres connection string>
31
-
NUXT_ENCRYPTION_KEY=<32-byte base64 key for sealing ssh private keys>
32
-
NUXT_CRON_SECRET=<shared secret for the worker cron route>
38
+
```bash
39
+
pnpm gen:jwk # NUXT_ATPROTO_PRIVATE_JWK
40
+
pnpm gen:encryption-key # NUXT_ENCRYPTION_KEY and NUXT_SESSION_PASSWORD
41
+
pnpm gen:cron-secret # NUXT_CRON_SECRET
33
42
```
34
43
35
-
### Setup
44
+
The rest (`NUXT_DATABASE_URL`, the `NUXT_GITHUB_APP_*` values) come from your
45
+
Neon dashboard and a [new GitHub App](https://github.com/settings/apps/new).
46
+
The App needs `contents:read` and `metadata:read` permissions plus the `push`,
47
+
`create`, `delete`, and `repository` events, with its webhook pointed at your
48
+
Smee URL.
49
+
50
+
In separate terminals, proxy webhooks and drain the job queue:
36
51
37
52
```bash
38
-
# install dependencies
39
-
corepack enable
40
-
pnpm install
53
+
smee --url <your-smee-url> --target http://127.0.0.1:3000/api/github/webhook
54
+
pnpm jobs:tick # run as needed; in production Vercel Cron does this
55
+
```
56
+
57
+
## Deploy to Vercel
58
+
59
+
synchub.to runs on Vercel with a Neon Postgres database.
41
60
42
-
# serve in dev mode, with hot reload at localhost:3000
43
-
pnpm dev
61
+
1. Apply migrations against your production database:
62
+
```bash
63
+
NUXT_DATABASE_URL="<pooled neon connection string>" pnpm db:migrate
64
+
```
65
+
2. Import the repo into Vercel (the Nuxt preset is auto-detected) and set every
66
+
variable from `.env.example` under **Settings > Environment Variables**.
67
+
Mark the secrets (`NUXT_DATABASE_URL`, `NUXT_GITHUB_APP_PRIVATE_KEY`,
68
+
`NUXT_ATPROTO_PRIVATE_JWK`, `NUXT_ENCRYPTION_KEY`, `NUXT_SESSION_PASSWORD`,
69
+
`NUXT_GITHUB_WEBHOOK_SECRET`, `NUXT_CRON_SECRET`) as **Sensitive**.
70
+
3. Set `NUXT_PUBLIC_URL` to your real origin and point the GitHub App webhook at
71
+
`https://<your-domain>/api/github/webhook`.
72
+
4. Deploy.
44
73
45
-
# build for production
46
-
pnpm build
74
+
The worker runs on a Vercel Cron (declared in `nuxt.config.ts`, so no
75
+
`vercel.json` is needed) and appears under **Settings > Cron Jobs** after the
76
+
first deploy.
47
77
48
-
# preview in production mode
49
-
pnpm preview
50
-
```
78
+
> [!NOTE]
79
+
> The GitHub App private key is multi-line, but Vercel env values are single
80
+
> line. Collapse the newlines to literal `\n` before pasting:
81
+
>
82
+
> ```bash
83
+
> awk 'NF {printf "%s\\n", $0}' your-app.private-key.pem
84
+
> ```
85
+
>
86
+
> Locally, keep the real newlines as shown in `.env.example`. Migrations are
87
+
> manual: re-run `pnpm db:migrate` against production whenever you ship a
88
+
> schema change.
51
89
52
90
## License
53
91