Review incoming git changes
When auto-merge is off, a push to the branch Archbee tracks does not change your space. Archbee holds the push and shows what it changes, and someone who can publish the space reviews and merges it. This works the same way for GitHub, GitLab, Bitbucket and Azure DevOps. The labels name your provider, so on GitLab the banner says GitLab instead of GitHub.
Auto-merge is off by default. To have pushes apply right away instead, see Turn auto-merge on or off.
What waits for review
These changes wait for review while auto-merge is off:
- A commit pushed to the tracked branch.
- A pull request merged into the tracked branch, including one that Archbee opened.
- A new branch selected in Space settings. Choosing the branch takes publish rights.
These changes apply right away, whatever the setting:
- The first import, when you create the space.
- Sync from repo in Space settings. While a push is waiting, only users who can publish the space can use it.
- A push that changes no document, folder, snippet or space setting, such as an edit to the README or to a CI file.
Archbee holds one push at a time. When a newer push arrives, it replaces the one that was waiting, and the review shows the newer changes.
Find the changes
Each document that the push changes shows a banner at the top. The banner names the commit, counts the changed documents and says when Archbee received the push. Its title says how the push affects the open document:
- This document is new in the repository
- This document has incoming changes from GitHub
- This document was removed in the repository
- Deleted in the repository, kept for the docs created in Archbee under it
- This document failed to convert in the last GitHub push
Documents the push does not touch show New changes from GitHub are waiting to be merged.
The left navigation marks every document in the push with a badge. Hover over a badge to read what the push does to that document. Documents that the push adds appear in grey italics, because they do not exist in Archbee until you merge.
You need write access to the space to see the banner, the badges and the changes.
Review the changes
Open the review. Click Compare on the banner of a changed document, or click its badge in the left navigation. From any other document, click Review changes, or View changes if you cannot publish the space.
In Review changes from GitHub, select a file in the list on the left:
- Content Changes lists the documents the push adds, changes or removes. Failed marks a file that did not convert to an Archbee document. Snippet marks a content snippet, which changes in every space that embeds it.
- Portal Tree Changes lists moves, renames and new folders. It also lists changes to space settings that come from the config file, such as Custom CSS.
Compare the current content with the incoming content. Switch between Diff View and MD View to see the change as blocks or as Markdown.
Merge the changes
To apply the push, click Merge changes at the bottom of the review. Only users who can publish the space see this button.
Before you merge, read the notice at the bottom of the review. Merging does the following:
- It replaces the current content of every changed document with the content from the repository.
- It discards the Archbee drafts of those documents. The notice names them.
- It applies the folder and order changes from the repository.
- It writes a placeholder body for each document that failed to convert.
- It updates each changed content snippet in every space that uses it.
If the merge fails, the banner shows Could not merge the changes from GitHub and the reason, for example that the branch no longer exists. Fix the cause in the repository, then merge again.
If a newer push arrives while you review, Archbee refreshes the review. Look at the new changes before you merge.
Archbee keeps a document that the repository deletes when the document holds documents created in Archbee. The review lists it under Portal Tree Changes as Deleted in the repository, kept.
Turn auto-merge on or off
You need publish rights on the space to change auto-merge.
Click the gear icon next to the space name to open Space settings.
Under PUBLIC DOCS SETTINGS, open the integration for your provider, such as GitHub Integration.
Turn Auto-merge pushes on or off.
Turning auto-merge on in Space settings affects later pushes only. A push that is already waiting stays until you merge it. To turn auto-merge on and merge the waiting push in one step, click Why am I seeing this? on the banner, then Turn on auto-merge.
Set auto-merge in the config file
You can also set auto-merge in the repository, with autoMerge in archbee.json or in your YAML config file:
{
"docsPath": "docs/",
"autoMerge": true
}Archbee reads the value on each push:
- autoMerge must be true or false. A string such as "false" is ignored.
- Without autoMerge, "publishSpace": true turns auto-merge on.
- Archbee applies the value from the config file only when it changes. If you switch auto-merge in Space settings later, your switch stays until someone edits autoMerge in the repository again.
- The push that changes autoMerge already follows the new value.
- When Archbee opens a pull request, it writes the space's current setting into archbee.json.
Disconnect the repository
When you remove the git integration from a space, Archbee drops the waiting push. The banner and the badges disappear, and the space keeps its current content.