Breadcrumbs

Servers

Servers

Adding a Server

  1. Log in as an administrator

  2. Navigate to Settings and choose Add-ons or Apps

  3. Find Git for Confluence in the menu on the left and choose Configure Git Servers

  4. Choose New Server

  5. Enter the server's details: Name, Connection Protocol, Host and Port

  6. Choose the Authentication Method

  7. Depending on the Authentication Method, enter further details

Authentication Methods

Git for Confluence supports two primary authentication methods. Choose based on your network and security requirements:

HTTPS with Access Tokens

  • Good for: Corporate networks where SSH (port 22) is blocked

  • Good for: Environments requiring token-based authentication

  • Consider: Tokens may need periodic rotation based on your security policies

SSH with Private Keys

  • Good for: Teams already using SSH key authentication

  • Good for: Long-term authentication without token rotation

  • Consider: Requires port 22 outbound access

HTTPS Authentication with Access Tokens

For connections to Git providers, HTTPS with access tokens works well in corporate environments where SSH may be restricted.

General setup:

  • Connection Protocol: https://

  • Authentication Method: Username and password

  • Username: Any value (required field) - can be your actual username or department name

  • Password: Paste your access token here

Note: The username field is required by the plugin but the actual value doesn't matter when using access tokens. All providers authenticate using the token in the password field.

Provider-Specific Token Creation

GitHub

Server configuration:

  • Host: github.com

  • Port: 443 (default)

Creating Personal Access Tokens:

  • Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)

  • Generate new token with repo permission (for private repos) or public_repo (for public repos)

  • For organizations: Use Fine-grained personal access tokens with repository access

Authentication:

  • Username: Your GitHub username or any placeholder

  • Password: Your personal access token

GitLab

Server configuration:

  • Host: gitlab.com (or your GitLab instance URL)

  • Port: 443 (default)

Creating Access Tokens:

  • Project Access Token: Project → Settings → Access Tokens, create token with read_repository permission

  • Group Access Token: Group → Settings → Access Tokens, create token with read_repository permission

  • Personal Access Token: User Settings → Access Tokens, create token with read_repository permission

Authentication:

  • Username: Any value (GitLab username, department name, or placeholder)

  • Password: Your access token

Bitbucket

Server configuration:

  • Host: bitbucket.org

  • Port: 443 (default)

Creating App Passwords:

  • Go to Bitbucket → Personal settings → App passwords

  • Create app password with Repositories: Read permission

  • For team repositories, ensure you have appropriate team access

Authentication:

  • Username: Your Bitbucket username

  • Password: Your app password (not your account password)

Azure DevOps

Server configuration:

  • Host: dev.azure.com (for Azure DevOps Services)

  • Port: 443 (default)

Creating Personal Access Tokens:

  • Go to Azure DevOps → User settings → Personal access tokens

  • Create new token with Code (read) scope

  • Set appropriate expiration date

Authentication:

  • Username: Any value (often just use your email or organization name)

  • Password: Your personal access token

SSH Private Key Authentication

When using private key authentication, the path to the key file is on the server. There is currently no option to upload keys to the server.

To add a private key:

  1. Log in as an administrator

  2. Navigate to Settings and choose Add-ons or Apps

  3. Find Git for Confluence in the menu on the left and choose Configure Git Servers

  4. Click on the edit icon

  5. Select private key as Authentication Method

  6. Enter the absolute path to your private key file

Requirements:

  • Private key should be in OpenSSH format (not PuTTY .ppk)

  • Key file permissions should be 600 (readable only by Confluence user)

  • Path should be absolute, not relative

  • Corresponding public key must be added to your Git provider

Common Issues & Solutions

Connection Problems

Connection hanging or timeout:

  • SSH connections failing → Check if port 22 is blocked, try HTTPS method instead

  • HTTPS connections failing → Verify port 443 access to the Git provider

Authentication errors:

  • "Authentication required but no CredentialsProvider" → Using HTTPS protocol with SSH private key method (or vice versa)

  • "Invalid credentials" → Check token permissions and expiration

  • "Repository not found" → Verify token has access to the specific repository

Protocol/Authentication Mismatches

Important: Don't mix protocols and authentication methods:

  • SSH protocol requires private key authentication

  • HTTPS protocol works with username/password (including tokens)

  • Don't use SSH URLs (git@github.com:...) with HTTPS protocol settings

Token Permissions

Make sure your tokens have sufficient permissions:

  • GitHub: repo for private repositories, public_repo for public repositories

  • GitLab: read_repository minimum

  • Bitbucket: Repositories: Read minimum

  • Azure DevOps: Code (read) minimum

SSH Key Issues

"Invalid private key" errors:

  • Check key format (should be OpenSSH format)

  • Verify file permissions (600)

  • Ensure the corresponding public key is added to your Git provider

  • Test SSH connection manually: ssh -T git@github.com -i /path/to/your/private/key