Git is a version control system for tracking changes in computer files and coordinating work on those files among multiple people.
¶ Getting Started
Probably the most popular way to store documentation, the Git module can effortlessly synchronize with any remote Git repository.
For convenience, instructions for the most popular Git providers are listed below. However, this module should work for virtually any standard Git provider.
You must have Git 2.7.4 or later installed on the system to enable this module!
The docker image already contains this dependency.
A Git repository must be dedicated to Wiki.js. It is not possible to use only a subfolder or submodules at the moment.
¶ Providers
¶ Azure DevOps
Coming soon!
¶ BitBucket
Coming soon!
¶ GitHub
GitHub is the most popular git source control provider.
¶ Generate a new key
- Open Terminal.
- Enter the command:
ssh-keygen -t rsa -b 4096 - When prompted to save the generated file, enter a path which can be accessed by Wiki.js (e.g.
/etc/wiki/github.pem) and press Enter. - Leave the passphrase empty and press Enter twice. Password-protected keys will NOT work.
On Windows, you can use Git Bash or Windows Subsystem for Linux (WSL) distributions like Ubuntu for Windows to run the commands above. You can also generate keys manually using the puttygen utility.
¶ Add the key to GitHub
- Create a new GitHub repository.
- Click on the Settings tab.
- Click on the Deploy Keys in the left navigation menu.
- Click the Add deploy key button.
- Enter a name of your choice for this key (e.g. wiki) and paste the contents of the public key generated earlier. (file ending in
.pub) - Make sure the Allow write access is checked.
- Click the Add key button.
¶ Configure Wiki.js
- In the Administration Area, click on Storage in the left navigation menu.
- Make sure the Git storage target is checked.
- Click on the Git tab.
- Enter the following settings:
- Authentication Type:
ssh - Repository URI: On your GitHub repository page, in the Code tab, click on the Clone or download green button and copy the URI shown below Clone with SSH.
- Branch:
main - SSH Private Key Path: The path to your private key generated earlier.
- Username: Empty
- Password: Empty
- Default Author Email: Should match your GitHub account email.
- Default Author Name: Should match your GitHub account name.
- Local Repository Path: Choose where the repo will be cloned locally or leave the default
./data/repovalue. - Verify SSL Certificate: On
- Authentication Type:
- Set the Sync Direction to Bi-directional.
- Set the Sync Schedule to 5 minutes.
- Click the Apply Changes button at the top of the page.
- Wait for the Status panel to update. A new entry for Git should appear in green. If the bar is red, it means you have an error in your configuration. Go back to the Git tab, fix the error and try again.
¶ GitLab
Coming soon!
¶ Common Scenarios
¶ Import Content
When enabling the Git storage module for the first time with a remote repository that already has content, you might need to initiate a manual import. By default, only changes between the latest local commit and the latest remote commit will be imported.
Heads up! Make sure the Git module is already configured and working before proceeding any further!
To force an import of all content currently present in the local repository, load the Git module settings tab in the Administration Area (under Storage), scroll to the very bottom of the page and click Run button on the Import Everything action card.
¶ Missing Content in Remote Repository
If content was created in Wiki.js before you enabled the Git storage module or if you temporarily disabled the module, that content will be missing from the remote Git repository.
Heads up! Make sure the Git module is already configured and working before proceeding any further!
To fix this issue, load the Git module settings tab in the Administration Area (under Storage), scroll to the very bottom of the page and click Run button on the Add Untracked Changes action card. This will force all content currently in the DB to be output to files in the local repository, add these files to git tracking and create a single commit.
Note that this will not perform a sync with your remote repository. You must either wait for the next synchronization to occur, or manually force a sync using the Force Sync action.
¶ Frequently Asked Questions
¶ Why content is not synced when I save a page?
For performance reasons, new commits are only synced on a regular interval (every 5 minutes by default). You can change the schedule in the Git storage module settings.
¶ How can I force a manual sync?
Load the Git module settings tab in the Administration Area (under Storage), scroll to the very bottom of the page and click Run button on the Force Sync action card.
