Overview

Contentrain is a Git-based Headless CMS, which means all your content, models, and assets are stored directly in your Git repository. This approach gives you full ownership of your data, version history for every change, and seamless integration with your existing development workflow.

To make this possible, Contentrain needs to connect to a Git provider. The Git provider serves as the storage layer where your content lives. Every content change you make through Contentrain is committed to your repository, and every project you create in Contentrain is linked to a specific repository on your connected Git account.

Contentrain currently supports two Git providers:

• GitHub — Fully supported and available for all users.
• GitLab — Supported as an additional provider option.

Important

Different Git providers cannot be used within the same Contentrain account. Once you connect a Git provider to your primary workspace, all subsequent workspaces under that account must use the same provider.

GitHub Integration

GitHub is the primary Git provider for Contentrain. Connecting your GitHub account allows Contentrain to access your repositories, commit content changes, and manage branches on your behalf.

How to Connect GitHub

1. When you first log in to Contentrain, you will be prompted to connect a Git provider to your primary workspace. Click the "Connect Git provider" button.
2. Select GitHub as your provider and click "Next".
3. You will be redirected to GitHub's authorization page. Click "Authorize Contentrain" to grant the necessary permissions.
4. After authorization, click "Account settings" to select which GitHub account to install Contentrain on.
5. On the GitHub permissions page, choose whether to grant access to All Repositories or only selected repositories, then click "Install and Authorize".
6. You will be redirected back to Contentrain where you can select a repository and complete the setup.

Permissions Required

When you install Contentrain on your GitHub account, the following permissions are requested:

Permission	Purpose
Repository access	Read and write access to repository contents, allowing Contentrain to commit content changes.
Branch management	Ability to create and manage branches, which Contentrain uses for its dedicated content branch.
Pull requests	Ability to create pull requests for merging content changes from the Contentrain branch to your main branch.

You can choose to grant access to all repositories or only specific ones. If you select specific repositories, only those will be available for project creation in Contentrain.

Managing Permissions

You can update repository permissions at any time through your workspace's Git settings or directly from your GitHub account settings under Applications > Contentrain.

What Happens During Connection

When you connect your GitHub account to Contentrain:

• Contentrain installs as a GitHub App on your selected account.
• A dedicated contentrain branch is created in each project repository to isolate content changes from your codebase.
• All content operations (creating, updating, deleting content) are committed to this branch.
• Depending on your merge settings, pull requests can be opened automatically or managed manually.

GitLab Integration

GitLab is also supported as a Git provider in Contentrain. The connection process is similar to GitHub, with GitLab-specific authorization flows.

How to Connect GitLab

1. During workspace setup, select GitLab as your Git provider.
2. You will be redirected to GitLab's authorization page to grant Contentrain access.
3. Authorize the application and select the account or group you want to connect.
4. Choose which projects (repositories) Contentrain should have access to.
5. Complete the setup by selecting a repository for your workspace.

Permissions Required

Permission	Purpose
API access	Allows Contentrain to interact with your GitLab projects, including reading and writing repository contents.
Repository read/write	Enables Contentrain to commit content changes and manage branches within your projects.

GitLab Groups

When connecting a GitLab account for a secondary workspace, ensure you have the necessary owner or maintainer permissions on the GitLab group you want to use.

Managing Git Providers

Viewing Your Connected Provider

You can view and manage your connected Git provider through the Git settings tab in your workspace settings. This section displays:

• The currently connected Git provider and account.
• A list of repositories that Contentrain has access to.
• Options to manage permissions or disconnect the account.

Managing Repository Permissions

To add or remove repository access after the initial setup:

1. Navigate to your workspace Settings > Git settings.
2. Click "Manage permissions" to be redirected to your Git provider's settings page.
3. Update the repository access as needed and save your changes.
4. The updated repository list will be reflected in Contentrain.

Disconnecting a Git Provider

If you need to disconnect your Git provider from a workspace:

1. Go to your workspace Settings > Git settings.
2. Click "Disconnect".
3. Enter the Git account name to confirm, then click "Disconnect" again.

DANGER

If you disconnect the Git provider from your workspace, you will not be able to use that workspace until you connect a new Git repository. All projects within the workspace will become inaccessible.

Switching Between Providers

Contentrain does not support switching between different Git providers (e.g., from GitHub to GitLab) within the same account. The provider you select for your primary workspace applies to all workspaces under that account.

If you need to use a different Git provider, you must create a new Contentrain account.

Troubleshooting Common Issues

Authentication Failures

If you encounter issues during the authorization process:

• Clear your browser cache and cookies, then try the connection process again.
• Check that you are logged into the correct Git account in your browser before starting the authorization.
• Ensure pop-ups are not blocked, as the authorization flow may open in a new window.
• If the authorization page does not redirect you back to Contentrain, try the process again from the workspace settings.

Permission Errors

If Contentrain cannot access your repositories or commit changes:

• Verify that Contentrain is still installed on your Git account. Go to your GitHub or GitLab account settings and check installed applications.
• Check repository access to ensure the target repository is included in Contentrain's permissions.
• Re-authorize if necessary by navigating to workspace Settings > Git settings and clicking "Manage permissions".

Repository Not Appearing

If a repository does not appear in the Contentrain repository selection:

• Ensure you have granted Contentrain access to that specific repository (if you chose selected repositories instead of all).
• Check that the repository does not already have a Contentrain installation. A repository cannot be set up with Contentrain more than once.
• Verify that you have sufficient permissions (owner or admin) on the repository.

Push or Sync Failures

If content changes are not being pushed to your repository:

• Check that the Contentrain branch exists in your repository and has not been deleted.
• Verify your Git provider account is still connected by checking workspace Settings > Git settings.
• If the issue persists, try disconnecting and reconnecting your Git provider.

Need More Help?

For step-by-step instructions on setting up workspaces and connecting Git providers during workspace creation, refer to the Working with Workspaces guide. If you continue to experience issues, reach out through the Support section in your Contentrain dashboard.