mirror of
https://github.com/tdurieux/anonymous_github.git
synced 2026-10-19 22:27:20 +02:00
Thomas Durieux
445a479339
* fix: prevent duplicate access alerts to the same recipient * fix: address recipient alert recovery review findings * fix: reconcile unsent alerts and wait for startup migration * fix: preserve legacy recipient alerts through upgrades * fix: reconcile alert results and legacy recovery races * fix: fence dispatch and clean cancelled alert metadata * fix: fence alert preparation and retain in-flight recovery * fix: atomically commit alert dispatch and retry deferred recovery * fix: keep recovery lookups from blocking upstream file reads
227 lines
12 KiB
Markdown
227 lines
12 KiB
Markdown
<div align="center">
|
|
|
|
# Anonymous GitHub
|
|
|
|
**Share your code and data for double-anonymous peer review — without giving your identity away.**
|
|
|
|
[](https://www.npmjs.com/package/@tdurieux/anonymous_github)
|
|
[](LICENSE)
|
|
[](https://anonymous.4open.science/)
|
|
[](https://github.com/tdurieux/anonymous_github/stargazers)
|
|
|
|
[**Public instance**](https://anonymous.4open.science/) · [How it works](#how-it-works) · [Self-hosting](#self-hosting)
|
|
|
|
|
|
|
|
</div>
|
|
|
|
## Why
|
|
|
|
Double-anonymous review asks you to anonymize the artifact behind your paper — the code and data — exactly like the paper itself. Doing that by hand (owner, organization, repository name, logins, and every mention buried in the files) is tedious and easy to get wrong. Anonymous GitHub does it for you and serves the result behind a shareable link.
|
|
|
|
A free public instance is available at **[anonymous.4open.science](https://anonymous.4open.science/)**.
|
|
|
|
## What it anonymizes
|
|
|
|
- The GitHub **owner, organization, and repository name**
|
|
- **File and directory names**
|
|
- **File contents** of every extension (Markdown, text, source code, …), replacing a configurable list of terms
|
|
|
|
## Usage
|
|
|
|
### Public instance
|
|
|
|
Just open **[anonymous.4open.science](https://anonymous.4open.science/)**, paste your repository URL, add the terms to hide, and share the generated link.
|
|
|
|
### CLI
|
|
|
|
Anonymize a repository locally and produce an anonymized zip:
|
|
|
|
```bash
|
|
npm install -g @tdurieux/anonymous_github
|
|
anonymous_github
|
|
```
|
|
|
|
## Self-hosting
|
|
|
|
Local installation requires Node.js 22.15 or newer in the 22.x series,
|
|
24.x, or 26 or newer. Run `npm ci` and `npm run build` to install and build.
|
|
`npm run dev` uses Node's watch mode; `npm run build:ui` rebuilds browser assets.
|
|
|
|
<details>
|
|
<summary>Run your own instance with Docker</summary>
|
|
|
|
**1. Clone and install**
|
|
|
|
```bash
|
|
git clone https://github.com/tdurieux/anonymous_github/
|
|
cd anonymous_github
|
|
npm i
|
|
```
|
|
|
|
**2. Configure GitHub access** — create a `.env` file:
|
|
|
|
```env
|
|
GITHUB_TOKEN=<GITHUB_TOKEN>
|
|
CLIENT_ID=<CLIENT_ID>
|
|
CLIENT_SECRET=<CLIENT_SECRET>
|
|
CREDENTIAL_KEYS='{"2026-09":"<base64-encoded 32-byte random key>"}'
|
|
CREDENTIAL_ACTIVE_KEY_ID=2026-09
|
|
CREDENTIAL_LEGACY_READS=false
|
|
PORT=5000
|
|
DB_USERNAME=
|
|
DB_PASSWORD=
|
|
AUTH_CALLBACK=http://localhost:5000/github/auth
|
|
```
|
|
|
|
- `GITHUB_TOKEN` — create one at <https://github.com/settings/tokens/new> with the `repo` scope.
|
|
- `CREDENTIAL_KEYS` / `CREDENTIAL_ACTIVE_KEY_ID` — generate a key with `openssl rand -base64 32`. Existing installations must follow the [credential migration guide](docs/credential-encryption.md) before starting this release.
|
|
- `CLIENT_ID` / `CLIENT_SECRET` — from an OAuth App at <https://github.com/settings/applications/new>.
|
|
- The App's callback must be `https://<host>/github/auth` (matching `AUTH_CALLBACK`).
|
|
|
|
To enable read-only access to selected private repositories alongside OAuth, follow
|
|
the [GitHub App setup guide](docs/github-app-setup.md).
|
|
|
|
**3. Start the server**
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
**4. Open** <http://localhost:5000>. The port can be changed in `docker-compose.yml`; putting Anonymous GitHub behind nginx is recommended for HTTPS.
|
|
|
|
For an optional remote, hidden, delayed MongoDB replica and backup source, see
|
|
the [MongoDB replication guide](docs/mongodb-replication.md).
|
|
|
|
</details>
|
|
|
|
### Owner email alerts
|
|
|
|
Set `RESEND_API_KEY` and `EMAIL_FROM` on the web server and download workers to
|
|
send access alerts through [Resend](https://resend.com/docs/api-reference/emails/send-email).
|
|
Use a sender address on a domain verified in Resend. `APP_HOSTNAME` sets the
|
|
host used for the connections link in emails.
|
|
|
|
Registration saves a verified GitHub email address, preferring the primary address.
|
|
OAuth requests `user:email`; GitHub App sign-in uses the read-only email permission
|
|
described in the setup guide. Later sign-ins also fill missing addresses. Saved
|
|
addresses and custom alert addresses are preserved. GitHub privacy placeholder
|
|
addresses are not imported.
|
|
|
|
Signed-in owners without an email address see an email form in a popup.
|
|
“Remind me later” dismisses it for the current login session; “Never” saves a
|
|
permanent preference on the account. Existing addresses are reused, and owners
|
|
can add or change their address on the connections page at any time.
|
|
Alerts cover invalid GitHub credentials and repository access errors encountered
|
|
while reading or refreshing content. No periodic access scan is performed.
|
|
Emails contain no repository names, anonymous URLs, or credentials.
|
|
|
|
An atomic recipient claim allows one email attempt across repositories, pull
|
|
requests, gists and accounts sharing the same address. Sign-in does not reopen
|
|
alerts. An explicit reconnect or resource change prepares recovery, but the
|
|
recipient stays blocked until a fresh GitHub read confirms access to the resource
|
|
that triggered the alert. A fresh read during an in-flight send is retained and
|
|
applied when that send completes. A newer reset or source change invalidates
|
|
that recovery evidence. Cached reads and successful reads of other resources
|
|
cannot reopen it. Removed or expired resources and disabled owners no longer
|
|
block future alerts after their send has completed.
|
|
|
|
Dispatched recipient guards have no time expiry, so there are no daily reminders.
|
|
Failed deliveries remain blocked until confirmed recovery. An interrupted send
|
|
whose outcome is unknown stays blocked to avoid duplicate delivery. Unsent claims
|
|
can be cancelled by confirmed recovery before dispatch. Bookkeeping failures
|
|
release claims when no provider request has started. Pending claims interrupted
|
|
before dispatch can be reclaimed after a 60-second lease during startup or a new
|
|
notification attempt. Claim identity and state checks prevent a paused sender
|
|
from dispatching after another instance reclaims its claim. Cancellation is saved
|
|
before cleanup; matching legacy fields are cleared before the guard is released.
|
|
Interrupted cleanup resumes on startup or a later notification. Legacy fields
|
|
carry an attempt ID so unrelated deliveries and newer generations are preserved.
|
|
A resource revision prevents delayed preparation from recreating a reclaimed
|
|
claim. All asynchronous preparation stays pending. A sending reservation is
|
|
reclaimable until dispatch commits atomically on the owner document, against its
|
|
reset revision and lease, immediately before contacting the provider. Cancellation
|
|
competes with that same commitment, so a paused sender cannot dispatch afterward.
|
|
Owner dispatch records distinguish known-unsent reservations from interrupted
|
|
committed sends. Completed records are removed; expired uncommitted records are
|
|
pruned on later attempts. Persistent reset revisions also fence attempts created
|
|
while a reset is in progress, even when no recipient guard existed at its start.
|
|
Recovery recorded during an active reset is retried when reset finishes or its
|
|
lease expires, with the original source and revision checks.
|
|
Provider idempotency keys
|
|
and redacted attempt records support auditing without storing recipient addresses
|
|
or repository names in the audit log. Attempt records are saved before dispatch,
|
|
with completion recorded separately. Existing resource claims are migrated to
|
|
recipient guards before new application instances serve requests using an indexed
|
|
scan with resumable checkpoints. Other instances wait while its lease is healthy,
|
|
and take over if the lease expires.
|
|
Every existing resource claim is retained behind the recipient guard. Recovering
|
|
one resource atomically marks its claim recovered; other claims keep the recipient
|
|
blocked until they recover or are retired. A newer owner reset makes its matching
|
|
claims require another fresh read. Completed provider results are recorded before
|
|
guard updates, with bounded retries and reconciliation on startup or a later
|
|
notification. Retirement also checks the latest owner reset revision.
|
|
|
|
Use `scripts/deploy.sh` for the first upgrade to recipient alerts. The new image
|
|
has the `science.4open.owner-alert-protocol=recipient-v1` label. When running
|
|
application containers lack that label, the script builds the replacement, stops
|
|
and verifies all old API and streamer containers, then prepares a full claim
|
|
reconciliation and starts the new streamers and API. Stopped legacy containers
|
|
from a rollback also trigger reconciliation, so claims written after an earlier
|
|
migration are included. This path also runs when retrying with an already-built
|
|
image and `FORCE=0`. Once writers are stopped, preparation releases all known
|
|
unsent pending claims and clears their matching legacy fields before backfill.
|
|
This upgrade pauses traffic while claims migrate and allows up to 15
|
|
minutes for startup, configurable with `MIGRATION_HEALTH_TIMEOUT`. Subsequent
|
|
deployments keep the usual rolling streamer replacement. Manual upgrades must
|
|
stop all legacy application writers, run
|
|
`docker compose run --rm --no-deps --entrypoint node anonymous_github ./build/scripts/reconcile-legacy-owner-alerts.js`
|
|
using the new image, and then start the new application instances. Run this
|
|
preparation after legacy writers have operated, even if their containers were
|
|
already removed. Ordinary restarts preserve confirmed recoveries.
|
|
Leaving either Resend setting empty disables delivery and the email prompt.
|
|
|
|
## Scope of anonymization
|
|
|
|
In double-anonymous review, the boundary of anonymization is **the paper plus its online appendix — and only that**. Googling part of the paper or appendix to reveal authorship is considered a deliberate attempt to break anonymity ([explanation](https://www.monperrus.net/martin/open-science-double-blind)).
|
|
|
|
## How it works
|
|
|
|
Anonymous GitHub either downloads the full repository and anonymizes each file, or proxies requests to GitHub on the fly. In both cases the original and anonymized versions are cached on the server, so even large repositories stay responsive.
|
|
|
|
## Related tools
|
|
|
|
- [gitmask](https://www.gitmask.com/) — contribute anonymously to a GitHub repository.
|
|
- [blind-reviews](https://github.com/zombie/blind-reviews/) — browser add-on that hides identifying information when reviewing a pull request.
|
|
|
|
## See also
|
|
|
|
- [Open science and double-anonymous peer review](https://www.monperrus.net/martin/open-science-double-blind)
|
|
- [ACM policy on double-blind reviewing](https://dl.acm.org/journal/tods/DoubleBlindPolicy)
|
|
|
|
## License
|
|
|
|
[GPL-3.0](LICENSE) © [Thomas Durieux](https://durieux.me)
|
|
|
|
### Frontend development
|
|
|
|
The UI uses Vue 3 and Vue Router with the existing Express API. Page setup
|
|
functions live in `public/script/app.js` and `admin.js`; the Vue templates are
|
|
in `public/partials/`. Gulp compiles the templates and bundles the app with
|
|
esbuild, then updates the asset manifest used by Express.
|
|
|
|
Run `npm run build:ui` after changing a template or frontend script. Use
|
|
`npm run dev:ui` to serve the built UI locally with API requests proxied to the
|
|
configured upstream. `npm run test:ui` rebuilds the assets and runs the frontend
|
|
regression and DOM interaction tests. `npm run build` also builds the UI for
|
|
production.
|
|
|
|
The initial bundle contains the Vue app. Markdown extensions load on content
|
|
routes; PDF.js, Ace, and notebook support load when their viewers mount.
|
|
Org support loads in the repository explorer, and Mermaid loads only when a
|
|
diagram is encountered. These libraries use hashed URLs and load once per tab.
|
|
|
|
The Docker build compiles the same bundles and copies them, the asset manifest,
|
|
and document-worker assets into the runtime image. The Compose app serves these
|
|
assets directly; no frontend development server is needed.
|