Self-Hosted GitLab Integration Guide

This guide will walk you through the process of connecting your self-hosted GitLab server to DocuWriter.ai, allowing you to sync your repositories and generate documentation directly from your private GitLab instance.

Overview

To connect your self-hosted GitLab server to DocuWriter, you'll need to:

1. Create an OAuth application in your GitLab instance
2. Configure the application with the correct scopes and redirect URI
3. Obtain the Client ID and Client Secret
4. Connect your GitLab instance to DocuWriter using these credentials

Step 1: Access Your GitLab Profile Settings

1. Log in to your self-hosted GitLab instance
2. Click on your profile avatar in the top-right corner
3. Select "Edit profile" from the dropdown menu

Step 2: Navigate to Applications

1. In your profile settings, look for the left sidebar menu
2. Click on "Applications" in the left navigation panel

Step 3: Create a New Application

1. On the Applications page, click the "Add new application" button
2. You'll be presented with a form to create a new OAuth application

Step 4: Configure Your OAuth Application

Fill out the application form with the following details:

Application Details

• Name: Enter a descriptive name for your application (e.g., "DocuWriter Integration")
• Redirect URI: Enter the DocuWriter callback URL:

https://app.docuwriter.ai/auth/gitlab/callback

Required Scopes

Select the following scopes for your application:

• ✅ **api** - Access the authenticated user's API (required for export functionality and webhook creation)
• ✅ **read_user** - Read the authenticated user's personal information
• ✅ **read_repository** - Grants read-only access to repositories
• ✅ **read_api** - Grants read access to the API, including all groups and projects
• ✅ **write_repository** - Grants read-write access to repositories (required for export functionality)

Optional Settings

⚠️ Critical: Scope Configuration for Self-Hosted GitLab Important: For self-hosted GitLab instances, OAuth scopes are fixed when you create the OAuth application. Unlike gitlab.com, you cannot update scopes dynamically after the application is created. What this means: - You must select all required scopes when creating your OAuth application - If you need additional scopes later (e.g., for export functionality), you must update your GitLab OAuth application settings manually - DocuWriter will use the scopes that were originally granted when you first connected For full functionality, ensure you select: - api - Required for export functionality and webhook creation - write_repository - Required for exporting documentation to Git repositories - read_user, read_api, read_repository - Required for basic repository access If you encounter "The requested scope is invalid, unknown, or malformed" errors, it means the OAuth application doesn't have the required scopes. You'll need to edit your GitLab OAuth application and add the missing scopes.

• Confidential: Leave this checked (recommended for security)
• Expire access tokens: You can set this based on your organization's security policies

Step 5: Save and Retrieve Credentials

1. Click "Save application" to create your OAuth application
2. After saving, you'll be redirected to the application details page
3. Important: Copy and securely store the following credentials:
4. Application ID (Client ID)
5. Secret (Client Secret)

Step 6: Connect to DocuWriter.ai

Security Note: The Client Secret will only be displayed once. Make sure to copy it immediately and store it securely.

Now that you have your GitLab OAuth application configured, you can connect it to DocuWriter:

1. Log in to your DocuWriter account
2. Navigate to Git Connections
3. Click "Connect GitLab"

Step 7: Configure Self-Hosted GitLab in DocuWriter.ai

1. In the GitLab connection modal, enable "Use self-hosted GitLab instance"
2. Fill in the required information:
3. GitLab Instance URL: Your GitLab server URL (e.g., https://gitlab.company.com)
4. Client ID: The Application ID from Step 5
5. Client Secret: The Secret from Step 5
6. Click "Connect" to proceed with the OAuth flow

Step 8: Complete the Authorization

1. You'll be redirected to your GitLab instance for authorization
2. Review the permissions requested by DocuWriter
3. Click "Authorize" to grant access

You'll be redirected back to DocuWriter.ai with a successful connection

Step 9: Verify Your Connection

After successful authorization:

1. You should see a confirmation message in DocuWriter.ai
2. Your GitLab repositories should now be available for selection
3. You can now create documentation projects using your self-hosted GitLab repositories

Troubleshooting

If you encounter issues during setup or while using the integration, refer to the solutions below.

Invalid Redirect URI Error

What you'll see: GitLab shows an "Invalid redirect URI" error during OAuth flow.

How to fix:

1. Open your GitLab OAuth application settings
2. Verify the Redirect URI exactly matches: https://app.docuwriter.ai/auth/gitlab/callback
3. Check for:
4. Trailing slashes (should not have one)
5. Typos or extra spaces
6. HTTP vs HTTPS mismatch

Application Not Found Error

What you'll see: DocuWriter cannot connect to your GitLab instance.

How to fix:

1. Verify Instance URL: Check that your GitLab instance URL is correct and accessible

2. Test by opening the URL in your browser

3. Ensure it includes https:// protocol

4. Check Network Access: Ensure your GitLab instance is reachable from the internet

5. DocuWriter needs to connect from external servers

6. Check firewall rules if applicable

7. Verify HTTPS: Confirm HTTPS is properly configured

8. Self-hosted instances must use valid SSL certificates

9. Check certificate expiration

Insufficient Scope Error

What you'll see: DocuWriter cannot access your repositories or user information.

How to fix:

1. Go to your GitLab instance → Profile Settings → Applications
2. Find your DocuWriter OAuth application
3. Edit the application
4. Verify all required scopes are selected:
5. api
6. read_user
7. read_repository
8. read_api
9. write_repository
10. Save the application
11. Disconnect and reconnect your GitLab integration in DocuWriter

"The Requested Scope is Invalid, Unknown, or Malformed" Error

What you'll see: This error appears when trying to export documentation or update permissions.

Why this happens: Self-hosted GitLab instances have fixed OAuth scopes that cannot be updated dynamically. Unlike gitlab.com, you cannot request additional scopes after the initial connection.

How to fix:

1. Go to your GitLab instance → Profile Settings → Applications
2. Find your DocuWriter OAuth application
3. Click Edit to modify the application
4. In the Scopes section, ensure all required scopes are checked:
5. ✅ api (required for export and webhooks)
6. ✅ write_repository (required for export)
7. ✅ read_user (required for basic access)
8. ✅ read_api (required for basic access)
9. ✅ read_repository (required for basic access)
10. Click Save application
11. Return to DocuWriter and disconnect your GitLab integration
12. Reconnect your GitLab integration in DocuWriter

Important: All scopes must be configured in the GitLab OAuth application settings. DocuWriter cannot request additional scopes after the initial connection.

SSL Certificate Issues

What you'll see: Connection fails due to SSL certificate problems.

How to fix:

1. Check Certificate Validity: Ensure your GitLab instance has a valid SSL certificate

2. Certificate should not be expired

3. Certificate should be issued by a trusted CA

4. Self-Signed Certificates: If using self-signed certificates:

5. Contact DocuWriter support for assistance

6. We may be able to help configure certificate validation

Authentication Token Expired

What you'll see: Previously working connection stops working.

How to fix:

1. Go to DocuWriter → Git Connections
2. Find your GitLab integration
3. Click Disconnect
4. Reconnect your GitLab integration
5. If the issue persists, check if your GitLab access tokens have expired in GitLab's settings

Getting Additional Help

If you continue to experience issues after trying the solutions above:

Before contacting support, gather this information:

• Your GitLab instance URL (without credentials)
• The exact error message you're seeing
• Screenshots of the error (without sensitive information)
• Steps you've already tried

Check these resources:

1. GitLab Logs: Review your GitLab instance logs for any error messages

2. Look for OAuth-related errors

3. Check application logs

4. Network Connectivity: Verify DocuWriter can reach your GitLab instance

5. Test from external network if possible

6. Check firewall and security group rules

7. Contact Support: Reach out to DocuWriter support with the information above

8. Include all relevant details

9. We'll help troubleshoot your specific setup

Security Best Practices

For GitLab Administrators

1. Regular Credential Rotation: Periodically rotate your OAuth application credentials
2. Access Monitoring: Monitor OAuth application usage in GitLab's audit logs
3. Scope Limitation: Only grant the minimum required scopes (but ensure all necessary scopes are included)
4. Network Security: Ensure your GitLab instance is properly secured and only accessible via HTTPS

For DocuWriter Users

1. Credential Protection: Never share your Client ID and Client Secret
2. Access Review: Regularly review connected applications in your GitLab profile
3. Prompt Updates: Keep your GitLab instance updated with the latest security patches
4. Scope Management: When creating your OAuth application, include all scopes you might need (api, write_repository) to avoid having to update later

API Rate Limits

DocuWriter respects GitLab's API rate limits. If you encounter rate limiting issues:

1. Check GitLab Settings: Review your GitLab instance's rate limiting configuration
2. Monitor Usage: Use GitLab's admin panel to monitor API usage
3. Adjust Limits: Increase rate limits if necessary for your use case

Supported GitLab Versions

DocuWriter supports self-hosted GitLab instances running:

• GitLab Community Edition (CE) 13.0+
• GitLab Enterprise Edition (EE) 13.0+

For older versions, some features may not be available. We recommend keeping your GitLab instance updated to the latest stable version.

Next Steps

Once your self-hosted GitLab is connected to DocuWriter:

1. Repository Selection: Choose repositories you want to document
2. Branch Configuration: Select the appropriate branches for documentation generation
3. Documentation Creation: Start generating documentation from your code
4. Team Collaboration: Invite team members to collaborate on documentation

Conclusion

You have successfully integrated your self-hosted GitLab server with DocuWriter! Your repositories are now accessible for documentation generation, maintaining the security and privacy of your self-hosted environment while leveraging DocuWriter's powerful documentation capabilities.

Remember: For self-hosted GitLab instances, OAuth scopes are fixed when you create the application. Make sure to include all required scopes (api, write_repository, read_user, read_api, read_repository) from the start to enable all DocuWriter features including export functionality.

For additional features and advanced configuration options, please refer to our main documentation or contact our support team.