Troubleshooting - archimatetool/archi-modelrepository-plugin2 GitHub Wiki

Connecting to Git repositories is not always straightforward. There can be many factors involved - authentication, proxy settings, tokens, and so on. This page attempts to document some of the issues and offers some suggestions to solve them.

coArchi2 maintains a dedicated log file of all coArchi related actions and errors. Log files are named log-0.txt, log-1.txt in ascending order with the most recent log file having the latest number. The log files are located in the <user home>/Documents/Archi/repositories folder. If you are reporting a bug or issue with coArchi please attach the latest log file (or the relevant parts of the log file).

Some Git hosting providers such as GitHub require the use of a Personal Access Token (PAT) for HTTPS authentication.

Here are some examples on how to create a PAT:

• https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
• https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html
• https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html

Make sure you use your username and your PAT as your password.

Some Git repositories are hosted by servers that have certificates that the JRE (Java Runtime) used by Archi cannot verify. This is because the JRE certificate store does not have a complete certificate chain for these servers. This is the case when companies have issued their own certificates.

A temporary work around to see whether this might be the case is to disable certificate verification by editing the git config file, either globally or just for the local repository. The global location is <user home>/.gitconfig, and the following settings will disable SSL verification:

[https]
    sslVerify = false
[http]
    sslVerify = false

• Did you set the correct authentication details in the Repository Properties?
• Proxy configuration (if in use) - are the settings correct?
• Git server uses a self-signed certificate or one from a custom PKI (in such case the certificate must be manually added to the JVM's trust store)
• Access rights on the remote Git repository - check the user has access to the repository, branch or action
• Git platform access management based on user/password on the web frontend but requiring a token for repositories
• Git platform access management based on SSO on the web frontend but requiring a user/password or a token for repositories
• Possible issues related to MTU (Maximum Transmission Unit) when connecting via a VPN Enable SSO on my token (with a company account) - did you authorise the token against your SSO provider after you created it?

This error typically occurs when using Git to access a remote repository, and it indicates that the server hosting the repository does not allow the git-upload-pack command to be executed. This command is essential for some Git operations as it enables the client to retrieve objects and references from the remote repository.

1. Authentication/Authorization Issues

   • Cause: You lack the necessary permissions to access the repository, or your credentials are incorrect.
   • Solution:
     • Verify your credentials (username, password, or SSH key) are correct.
     • Ensure you have read access to the repository. If it’s hosted on platforms like GitHub, GitLab, or Bitbucket, check your role (e.g., collaborator, member).
     • For SSH, confirm your public key is added to the hosting service.
     • If using HTTPS, try re-authenticating or generating a new personal access token (PAT) with appropriate scopes (e.g., repo for GitHub).

2. Incorrect Repository URL

   • Cause: The repository URL might be incorrect or point to a non-Git endpoint.
   • Solution:
     • Double-check the URL. For example, ensure it ends with .git (e.g., https://github.com/user/repo.git).
     • If using SSH, verify the format (e.g., [email protected]:user/repo.git).

3. Server-Side Restrictions

   • Cause: Some Git servers (e.g., those behind proxies or custom setups) explicitly disable git-upload-pack for security or access control reasons.
   • Solution:
     • If you manage the server, check the Git configuration or proxy settings. For example, in Gitolite or custom Git servers, ensure git-upload-pack is enabled for the repository and user.
     • Contact the server administrator to confirm if there are restrictions or misconfigurations.
     • If using a service like Gerrit, ensure the repository is properly configured for Git protocol access.

4. Firewall or Network Issues

   • Cause: A firewall or network policy might be blocking Git commands.
   • Solution:
     • Verify network connectivity to the server using ping or telnet to the Git server’s port (e.g., 22 for SSH, 443 for HTTPS).
     • If on a corporate network, check with your IT team for proxy or firewall rules affecting Git operations.
     • Try switching between HTTPS and SSH protocols to bypass potential network blocks.

5. Specific Hosting Service Issues

   • GitHub: Ensure your PAT has the correct scopes and hasn’t expired. For private repositories, confirm you’re invited as a collaborator.
   • GitLab: Check project visibility (private, internal, public) and your access level (e.g., Developer, Maintainer).
   • Bitbucket: Verify app passwords or SSH keys are set up correctly.
   • Custom Servers: If using tools like Gitolite, ensure the repository is listed in the configuration file (e.g., gitolite.conf) with appropriate permissions (e.g., R for read).

This error can occur when performing coArchi operations like Import Remote Model to Workspace, Refresh, or Publish. The client fails to authenticate or lacks the necessary permissions.

1. Invalid or Missing Credentials

   • Cause: The credentials (username, password, personal access token, or SSH key) provided to JGit are incorrect, expired, or not set.
   • Solution:
     • Ensure the credentials are valid. For HTTPS, use a username and password or a personal access token (PAT). For GitHub, generate a PAT with repo scope at https://github.com/settings/tokens.
     • If using SSH, verify that the private key is correctly configured and the public key is registered with the Git hosting service (e.g., GitHub, GitLab).

2. Insufficient Repository Permissions

   • Cause: The authenticated user does not have permission to access the repository (e.g., read for cloning/fetching, write for pushing).
   • Solution:
     • Verify your access to the repository on the hosting service (e.g., GitHub, GitLab, Bitbucket). Ensure you’re a collaborator or have the required role (e.g., Developer, Maintainer).
     • For private repositories, confirm you’ve been granted access.
     • If using a custom Git server (e.g., Gitolite), check the server’s configuration (e.g., gitolite.conf) to ensure your user has R (read) or RW (read/write) permissions.

3. Incorrect Repository URL

   • Cause: The repository URL passed to JGit is incorrect or points to a non-Git endpoint.
   • Solution:
     • Double-check the URL format (e.g., https://github.com/user/repo.git or [email protected]:user/repo.git).

4. SSH Configuration Issues

   • Cause: coArchi cannot locate or use the SSH private key, or the SSH setup is incorrect.
   • Solution:
     • Ensure the private key file (e.g., ~/.ssh/id_ed25519) exists and matches the public key registered with the Git server.
     • Test SSH connectivity: ssh -T git@<hostname> (e.g., [email protected]).

5. Server-Side Restrictions

   • Cause: The Git server may restrict certain operations (e.g., git-upload-pack or git-receive-pack) due to security policies or misconfiguration.
   • Solution:
     • If you manage the server, check if git-upload-pack (for cloning/fetching) or git-receive-pack (for pushing) is enabled.
     • For hosted services, contact support or check for repository-specific restrictions (e.g., GitLab’s project visibility settings).
     • Ensure the server supports the protocol (HTTPS or SSH) used by JGit.

6. Network or Proxy Issues

   • Cause: A firewall, proxy, or network restriction is blocking the connection to the Git server.
   • Solution:
     • Verify network connectivity to the server (e.g., ping or telnet to port 22 for SSH or 443 for HTTPS).
     • Configure the proxy settings if required
     • If on a corporate network, consult your IT team to resolve proxy or firewall issues.

The REJECTED_NONFASTFORWARD error can occur when a Publish (Git "Push") operation is rejected by the remote repository because there are changes on the remote server that need to be fetched before publishing. Make sure you do a "Refresh" first before "Publish".

The REJECTED_OTHER_REASON error can occur when a Publish (Git "Push") operation is rejected by the remote repository for a reason not covered by standard rejection categories (like non-fast-forward, branch checked out, or permission issues). It’s a catch-all error indicating a generic or server-specific issue. The exact cause depends on the remote repository’s configuration.

Check the remote repository’s configuration. The remote repository might have settings that block the push, such as restrictions on pushing to certain branches or the user lacks specific permissions.