---
title: Review incoming git changes
slug: docs/review-incoming-git-changes
createdAt: 2026-10-20T10:00:00.000Z
---

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](docId:7pPnyOrTTGQfeZ_eRLBuC).

## 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.

:::hint{type="info"}
You need write access to the space to see the banner, the badges and the changes.
:::

## Review the changes

::::WorkflowBlock
:::WorkflowBlockItem
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.
:::

:::WorkflowBlockItem
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**.
:::

:::WorkflowBlockItem
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.

:::hint{type="warning"}
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.

::::WorkflowBlock
:::WorkflowBlockItem
Click the gear icon next to the space name to open **Space settings**.
:::

:::WorkflowBlockItem
Under **PUBLIC DOCS SETTINGS**, open the integration for your provider, such as **GitHub Integration**.
:::

:::WorkflowBlockItem
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:

:::CodeblockTabs
archbee.json

```json
{
  "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.