GitLab
Connect a GitLab account to Archbee, then sync its projects to doc spaces. Archbee works with projects on gitlab.com. Self-managed GitLab instances are not supported.
Only organization admins in Archbee can connect GitLab.
Connect GitLab
Archbee connects to GitLab with OAuth, as the GitLab user who signs in. It can sync the projects that this user is a member of. To let Archbee add the webhooks that keep spaces in sync, the user needs the Maintainer or Owner role on those projects.
In Archbee, open Organization Settings > Configurations and click the GitLab card (Connect GitLab account).
Click Connect with OAuth. GitLab asks you to authorize Archbee to use the API and to read repositories.
After you authorize Archbee, you return to Configurations, and the GitLab card shows Connected. Open the card to see your projects, grouped by GitLab group. Click Refresh GitLab data to load projects you joined later.
To connect a different GitLab user, open the card and click Reconnect with OAuth.
Create a space from a GitLab project
- Create a new space and select Write in GitLab.
- In Select Git Repo, choose the project. In Select Branch, choose the branch Archbee tracks.
- Click Add Space.
You can also click the + button (Create synced space) next to a project in the GitLab card. Choose a Space group and a branch, then click Create space.
When the import finishes, Archbee notifies you. If the project has no Archbee config file yet, Archbee also opens a merge request titled Setup for Archbee-powered Docs with an archbee.json file and starter pages. To configure the project yourself, see Set up the repository.
Connect an existing space
- Open the space's menu and click Sync with Git App, then Sync with GitLab.
- Choose the project and the branch.
- If the project has no archbee.json yet, follow Let's configure your repo: create the merge request, open it in GitLab, merge it, then click Check if merged.
- Click Add Space.
Connecting a space to a project replaces the content of the space with the content of the project. Try it on a copy of the space first.
Keep the space in sync
Archbee adds a webhook to the project. Each push to the tracked branch starts a sync. While auto-merge is off, which is the default, each push waits for review in Archbee. See Review incoming git changes.
To change how the space syncs, open Space settings > GitLab Integration:
- Git branch sets the branch Archbee tracks and opens merge requests on. Changing it takes publish rights on the space.
- Auto-merge pushes sets whether pushes apply right away or wait for review.
- Sync from repo replaces the space with the content of the project right away, even when auto-merge is off.
Send Archbee drafts to GitLab
Edit your documents as drafts. Click Publish Space in the top right corner. In the Update GitLab MR row, click Review & Push to PRs.
Review your changes, then click Push to GitLab MR. Archbee opens a merge request against the tracked branch, or updates the one it already opened.
Review and merge the merge request in GitLab. Archbee deletes the drafts that went into it and syncs the merged content. While auto-merge is off, the merged content waits for review in Archbee first.
Disconnect GitLab
To disconnect one space, open Space settings > GitLab Integration and click Remove GitLab integration.
To disconnect the whole organization, click Remove Integration at the bottom of the GitLab card, then confirm. Archbee removes its webhooks from the projects, disconnects every space that synced from GitLab and deletes the stored credentials. The spaces keep their content.
Differences from GitHub
- Archbee does not import shadow docs from GitLab. See Code base as Shadow docs.
- Each sync downloads every file in the docs folder again, so syncs of large projects take longer than on GitHub.
- Archbee connects as one GitLab user, not as an app installed on a group.