Synchronizace s GitHubem

Umožněte uživatelům synchronizovat jejich projekty s repozitáři na GitHubu nebo GitHub Enterprise.

Tuto funkci vyvinul projekt ayaka-notes/ayakaleaf-pro a upravil ji projekt yu-i-i/overleaf-cep. Je k dispozici od verze v6.2.0. Stále je ve stavu beta. Pokud narazíte na jakýkoli problém, uvítáme vaši zpětnou vazbu.

​

Nastavení synchronizace s GitHubem

Před použitím synchronizace s GitHubem musíte nejprve povolit git-bridge.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Navštivte nastavení pro vývojáře, vytvořte svou GitHub OAuth aplikaci a zkopírujte její CLIENT_ID a SECRET.

Poznámka: při vytváření OAuth App zadejte do pole Authorization callback URL ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback. Ayakaleaf Pro sestavuje stejnou adresu z OVERLEAF_SITE_URL, takže pro ni v config/variables.env není třeba nic nastavovat.

Poté přidejte následující nastavení do souborů s proměnnými prostředí Overleafu.

config/variables.env

# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback
# (Optional) GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808

Před konfigurací OAuth callback URL na GitHubu se ujistěte, že je OVERLEAF_SITE_URL nastaveno správně.

Pokud se nacházíte v regionu s omezeným přístupem k síti, možná budete muset pro přístup ke GitHubu nakonfigurovat proxy. Nastavte následující proměnnou prostředí: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Ujistěte se, že používání proxy je v souladu s místními zákony a předpisy.

GITHUB_SYNC_PROXY_URL musí být standardní dopředná HTTP/HTTPS proxy (např. HTTP port Clash). Zrcadla pro stahování z GitHubu, jako je gh-proxy.org, nejsou podporována.

Jako hostitele proxy nepoužívejte 127.0.0.1. Pokud proxy běží na hostitelském serveru, použijte LAN IP adresu serveru (např. 192.168.1.xx) a ujistěte se, že je proxy nakonfigurována tak, aby přijímala připojení ze zařízení v místní síti.

​

GitHub Enterprise

Podpora GitHub Enterprise je k dispozici od verze v6.3.1. Starší verze se připojují pouze k github.com a níže uvedené proměnné nemají žádný účinek.

Ve výchozím nastavení se synchronizace s GitHubem připojuje k github.com. Chcete-li použít GitHub Enterprise Server (hostovaný u vás) nebo GitHub Enterprise Cloud s rezidencí dat (GHE.com), nastavte GITHUB_SYNC_URL na webovou adresu své instance, tedy tu, přes kterou otevíráte repozitáře v prohlížeči.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

Koncové body REST a GraphQL API se z GITHUB_SYNC_URL odvozují stejným způsobem jako v GitHub CLI:

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com (výchozí)	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST (jakýkoli jiný)	https://HOST/api/v3	https://HOST/api/graphql

Koncové body API nastavujte pouze tehdy, když je vaše instance poskytuje jinde, například za API gateway:

Proměnná	Výchozí hodnota
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Odvozeno z GITHUB_SYNC_URL, viz tabulka výše
GITHUB_SYNC_GRAPHQL_URL	Odvozeno z GITHUB_SYNC_API_URL, pokud je nastavena (/api/v3 se změní na /api/graphql, jinak se připojí /graphql), jinak z GITHUB_SYNC_URL

• OAuth aplikaci vytvořte na své enterprise instanci (Settings → Developer settings → OAuth Apps); aplikace z github.com tam nefunguje. Callback URL je stejná: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL je pouze webová adresa. Nenastavujte ji na adresu API, jako je https://api.github.com nebo https://HOST/api/v3, a nepřidávejte cestu k organizaci.
• Všechny tři adresy musí odkazovat na stejnou instanci GitHubu.

Pokud vaše instance používá certifikát od soukromé certifikační autority, připojte certifikát CA do kontejneru a nastavte na něj NODE_EXTRA_CA_CERTS, např. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

Propojené účty a projekty patří k instanci, se kterou byly propojeny. Před přepnutím GITHUB_SYNC_URL na jinou instanci požádejte uživatele, aby zrušili propojení svého účtu GitHub a projektů.

​

Kdo může propojovat a synchronizovat

Stejně jako v Overleaf Cloud může projekt s repozitářem GitHub propojit pouze vlastník projektu. Po propojení jej může synchronizovat každý spolupracovník s oprávněním k úpravám.

Akce	Kdo ji může provést
Export projektu do nového repozitáře GitHub	Vlastník projektu
Import repozitáře GitHub do nového projektu	Kterýkoli uživatel, který se stane vlastníkem nového projektu
Pull, push a merge propojeného projektu	Vlastník a spolupracovníci s oprávněním k úpravám
Zrušení propojení projektu s jeho repozitářem	Vlastník projektu

• Overleaf komunikuje s GitHubem prostřednictvím účtu GitHub uživatele, který synchronizuje, takže každý spolupracovník, který synchronizuje, si propojí vlastní účet GitHub a musí mít oprávnění pushovat do výchozí větve repozitáře.
• Spolupracovníci s oprávněním pouze ke čtení nemohou pro projekt synchronizaci s GitHubem používat.

​

Q&A

Jak propojím projekt s GitHubem a synchronizuji ho?

Odpověď: V editoru otevřete Integrations a klikněte na GitHub. Pokud váš účet GitHub ještě není propojen, klikněte nejprve na Link to your GitHub account. V části Export Project to GitHub zadejte název repozitáře, v části Repository visibility zvolte Private a klikněte na Create a GitHub repository.

Poté stejná karta otevře Sync with GitHub, kde jsou uvedeny nové commity na GitHubu. Kliknutím na Sync commitnete své změny z Overleafu do výchozí větve a přenesete změny z GitHubu do projektu. Synchronizace probíhá oběma směry, ale spustí se pouze tehdy, když někdo klikne na Sync; plánovaná synchronizace neexistuje. Pokud se změnily obě strany, Overleaf provede merge přes dočasnou větev s názvem overleaf-YYYY-MM-DD-HHMMSS. Pokud tento merge obsahuje konflikt, proveďte merge větve na GitHubu sami a poté klikněte na I have manually merged. Continue.

Mohu do výchozí větve provést force push?

Odpověď: Nedoporučujeme to. Overleaf force push rozpozná, upozorní na něj a převezme přepsanou větev, přičemž sloučí změny provedené v Overleafu od poslední synchronizace. Abyste se vyhnuli nepříjemným překvapením, chraňte výchozí větev v nastavení repozitáře před force pushem.

Mohu přejmenovat výchozí větev propojeného projektu?

Odpověď: Prosím, nedělejte to. Overleaf nadále synchronizuje s větví, se kterou byl projekt propojen. Chcete-li synchronizovat s jinou větví, zrušte propojení projektu a poté importujte repozitář do nového projektu, který použije aktuální výchozí větev.

Synchronizace s GitHubem hlásí „Something wrong with GitHub request“

Odpověď: Tato zpráva znamená, že se server nemohl spojit s GitHubem, například kvůli problému se sítí, DNS, TLS nebo proxy. Úplnou chybu zobrazíte pomocí bin/logs web. Pokud server k připojení na GitHub potřebuje proxy, nastavte GITHUB_SYNC_PROXY_URL.

Mám v GitHub OAuth App vypnout „Expire user access tokens“?

Odpověď: Ano. Synchronizace s GitHubem neobnovuje tokeny, jejichž platnost vypršela. Se zapnutým vypršením tokenů musí uživatelé GitHub znovu připojit pokaždé, když jejich token vyprší.

Musí být moje instance dostupná z internetu?

Odpověď: Ne. Propojení účtu probíhá přes prohlížeč uživatele, takže adresa OAuth callbacku se musí otevřít pouze v prohlížeči uživatele. Server se potřebuje dostat jen k GitHubu; pokud k tomu potřebuje proxy, nastavte GITHUB_SYNC_PROXY_URL. GitHub vaši instanci nikdy nevolá: projekt se synchronizuje pouze tehdy, když jej uživatel synchronizuje v editoru.

Propojení mého účtu GitHub selže nebo mě vrátí zpět bez propojení

Odpověď: Zkontrolujte postupně následující:

• Otevírejte Overleaf přesně na adrese nastavené v OVERLEAF_SITE_URL. GitHub vás vrátí na ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback a vaše přihlášení existuje pouze na adrese, ze které jste začali, takže jiný hostitel, IP adresa nebo port skončí na přihlašovací stránce nebo na „Restricted, sorry you don’t have permission to load this page“.
• Authorization callback URL aplikace OAuth musí být ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback se stejným schématem, hostitelem a portem.
• Chybová stránka s Failed to obtain access token from Git server znamená, že GitHub nevrátil token: zkontrolujte GITHUB_SYNC_CLIENT_ID a GITHUB_SYNC_CLIENT_SECRET a také to, zda server může dosáhnout na GitHub. Úplnou chybu zobrazíte spuštěním bin/logs web.

Po změně config/variables.env spusťte bin/up, aby se kontejnery znovu vytvořily.

Import repozitáře selže s „EmptyZipFileError: empty_zip_file“ nebo „unzip failed“

Odpověď: Overleaf importuje zip archiv posledního commitu ve výchozí větvi repozitáře a tato chyba znamená, že archiv neobsahuje žádný soubor, který by Overleaf mohl importovat. Zkontrolujte výchozí větev na GitHubu:

• Obsahuje soubory projektu, nejen soubory, které Overleaf při importu přeskakuje: soubory začínající tečkou, jako .gitignore a .gitmodules (.latexmkrc se zachová), a soubory sestavení, jako *.aux, *.log, *.bbl, *.synctex.gz, *.doc a *.docx.
• Soubory nejsou pouze uvnitř submodulů Gitu. Archiv GitHubu ponechává submoduly jako prázdné složky.
• Očekávané soubory jsou ve výchozí větvi, nikoli v jiné větvi. Import vždy používá výchozí větev.

Import repozitáře selže s „connect ECONNREFUSED“ na „sharelatex:3054“

Odpověď: V1_HISTORY_URL je nastavena na http://sharelatex:3054, hodnotu, kterou uváděly starší verze této dokumentace. Port 3054 patří službě project-history, která naslouchá pouze uvnitř kontejneru, zatímco V1_HISTORY_URL musí ukazovat na history-v1. Overleaf ukládá každý binární soubor (obrázky, PDF) importovaného repozitáře do history-v1, takže import selže; stejně selže i nahrání takového souboru v editoru. Ve svém docker-compose.yml nastavte u služby sharelatex V1_HISTORY_URL: "http://sharelatex:3100/api" (viz Integrace s Gitem) a kontejner znovu vytvořte. Toolkit tuto hodnotu již nastavuje; zkontrolujte, zda ji nepřepisuje docker-compose.override.yml.