GitLab

Cartographer integrates with GitLab to scan your repositories for generating and updating documentation, or to create pull requests that create/update README files or other documents.

Connecting to GitLab

1. GitLab relies on access tokens to pass access your instance. Navigate to this link to generate a fine grained access token.
2. Click the Add new token button




3. Select the correct scopes:
   • For the Repository Scan feature, enable the read_repository and read_api permissions.
   • For updating README files or other documents, enable the write_repository and api permissions.
   • To use both features, enable both permission sets.




4. Click Create token and then save it for future use.
5. Navigate back to Cartographer. In the left-hand menu, click the Integrations navigation button.
6. In the top-right toolbar, click the Add GitLab Integration icon.




7. You’ll be directed to a form with four fields: Name, Owner Name, Repository Name, and API Key.
   • Name: A custom label of your choice.
   • Owner Name: The GitLab username of the repository owner.
   • Repository Name: The exact name of the repository in GitLab.
   • API Key: The previously generated key from GitLab.
   • After filling out the form, paste your API key into the field and click Save. Note: If the API key is invalid, the integration cannot be saved.
8. Once connected, the integration will appear in your table. You can edit or delete it at any time by clicking the chevron icon.

Repository Scan

Now that your GitLab integration is set up, you can access the Repository Sync from the left-hand navigation bar. Your connected repository will appear in the list, where you can scan it and continue using the sync feature.

Syncing your documents to GitLab

1. Navigate to the document you want to sync. In the top-right toolbar, click the ellipsis (⋯) and select Integrations.




2. Your GitLab integration will appear in the grid view. Click the Connect button to link your document to your GitLab instance.




3. A modal will appear prompting for two fields: Target Branch and File Name
   • Target Branch: The branch where your PR will be created. Defaults to main.
   • File Name: The name your page will have in your GitLab repository. Defaults to README.md




4. Once all required fields are filled out, click Save to connect.
5. Once your document is connected, you must click the Resync button in the bottom-right corner to create or update GitLab pages. This ensures that any edits, additions, or formatting changes in your Cartographer document are reflected in GitLab. Click Resync whenever you make changes to keep your GitLab repository up to date. Resyncing will create a new pull request if one is not alreay there.




6. To edit or delete a document integration, click the ellipsis (⋯) icon to access the available options.
7. That’s it! Your document is now viewable in your GitLab repository.