Articles on: Writing

Syncing articles to GitHub

This how-to guide will assume you have some basic knowledge of Git and that you have a Github account already. You can link your Authorea article with a Github repository very easily: in just one click.

Linking up Authorea and Github. From your article (main view):

Make sure you are an admin (if not, ask the lead author to make you so)
Click on the gear icon (Settings )
Scroll down to the Advanced Settings and click on Setup Github Integration under Offline mode
In the page that opens up, shown below, click on the big button Setup Github integration automatically


That’s it! Authorea and Github: connection established! Your Authorea article and Github repo are now seamlessly linked to one another. You should see a screen that tells you that the Git access bridge was successfully set up. This means that every change made to your Authorea article online will automatically be reflected on the Github repository. Similarly, when you (or your coauthors) work offline on the paper and then push their changes, the online article will automatically be updated.

Working offline. If you navigate back to your Github repository, you will see that all the basic Authorea files (bibliography folder, figures folder, etc) are now in the repo. You can now work offline using your editor of choice and push/pull to/from this Github repo to update the Authorea article. Note: if Authorea bumps into merging conflicts, it will push to a fail-safe branch called authorea .



Expert mode


LaTeX users. Most users who write in LaTeX will want to compile their articles from time to time when working offline. We advise users not to change the basic structure of the repository. For example, the file layout.md is crucial as it instructs Authorea what files to render. If you delete it, the Authorea article will break! In order to build your article locally when working offline we suggest to use this Python Script by our fellow Erik Tollerud.

Work offline using Bitbucket and Gitlab. If you use Bitbucket instead of Github, we have a solution for you too. The main problem with Bitbucket is that it does[not give](https://bitbucket.org/site/master/issue/8873/extend-deployment-keys-to-allow-both-read) write access to deploy keys. This is unfortunate but there is a workaround. Create a new user on Bitbucket, call it for example, user_authorea . Add an ssh key to the account and add that user to your Bitbucket repo that you would like to link to Authorea. On Authorea, paste in the private part of this ssh key when setting up git access. Setup the web hook on Bitbucket with the url supplied by Authorea and you should be good to go. Do you have a Gitlab installation? It should work following the manual setup described below. Contact us at help@authorea.com and we’ll help you if you have problems.

Git power users. If you are an expert Git user, you may want to avoid the automatic setup in favor of the manual setup so that you give Authorea more granular access rights to your Github repos. The following steps can guide you through the manual integration, click-by-click (thanks Rick Gerkin!):

Settings Icon / Delete your Deploy Key. / Delete the old one.
Settings Icon / Setup GitHub integration.
Manual / Generate SSH Key Pair.
Select All / Copy.
Go to https://github.com/your-user-name/your-repo-name/settings/keys
Add Deploy Key
Title: “Authorea”, Key: Paste from step 4.
Check “Allow write access”.
Click “Add Key”.
Back at Authorea, enter git@github.com:your-user-name/your-repo-name.git in Git repository URL.
Web hook / Select All / Copy.
Go to https://github.com/your-user-name/your-repo-name/settings/hooks
Click “Add webhook”.
Paste from step 10 into “Payload URL”.
Leave “Secret” blank.
Disable SSL verification.
Click “Add webhook”.
Back at Authorea, click “Submit” (leaving default branch as master).
Follow “Go to article git functions” link.
Click “Push” (got success message!)
Make edits to manuscript (appears successfully on GitHub).
You can download it directly from this url:
https://gist.github.com/eteq/1d7b138b9c4e80231f6f/raw/d535a5c0d7970fd3fd277e0902cec9b6be832106/local_build.py↩

Final note. This how-to is loosely based on a blog post by Joshua Ryan Smith called Migrating a LaTeXmanuscript hosted on GitHub to Authorea. We would like to thank Josh for writing the how to manual (before we did!) and Erik for putting together the offline LaTeX build script.



Updated on: 12/16/2017