Troubleshooting and frequently asked questions

The plugin is not listed in Redmine

1. Confirm that the plugin directory is exactly plugins/redmine_scm; an extra archive directory level prevents Redmine from finding it.
2. Run bundle install from the Redmine root with the same Ruby environment used by the service.
3. Run bundle exec rake redmine:plugins:migrate RAILS_ENV=production. The tables created by these migrations are required; SCM Creator does not repeatedly test or create them during normal requests.
4. Restart every Redmine web, job and scheduler process. A browser reload alone does not reload Rails plugins.
5. Check the production log during startup for dependency, migration or plugin-loading errors.

cd /opt/redmine
bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production

A repository provider is missing

Open Administration → Settings → Repositories and enable the required SCM. For local Git, Subversion, Mercurial and Bazaar, confirm that the matching executable is installed and available to the Redmine service account. For GitHub.com and VCSAdmin Git, copy and configure config/scm.yml. Restart all Redmine processes after changing provider configuration.

If the provider remains unavailable, inspect the startup log. A malformed YAML file, incorrect indentation, unavailable executable or missing environment variable is more informative there than in the repository form.

A user cannot create or manage a repository

• The project's Repository module must be enabled.
• The user's role needs Manage repository for creation or configuration; view permission alone is insufficient.
• Check the administrator's per-project repository limit and any setting that restricts management to the original creator.
• Confirm that the selected provider is enabled globally and fully configured on the server.

Local repository creation fails

1. Confirm that the configured provider root exists and is writable by the Redmine service account.
2. Keep repository paths as direct children of that root. Do not use traversal segments or point outside the configured root.
3. Run the provider executable as the service account and verify its configured path.
4. Check free disk space, filesystem quotas and optional lifecycle scripts. A failing hook must return a useful message in the Redmine log.
5. If creation partly succeeded, inspect the filesystem and Redmine registration before retrying so that an existing directory is not mistaken for a new repository.

GitHub.com connection, mirror or webhook fails

An existing public repository can be cloned from its complete GitHub.com URL without an API token. Private access, repository creation, credential tests and webhook registration require suitable credentials. A repository-specific encrypted token takes precedence over the environment token.

SCM Creator supports GitHub.com, not GitHub Enterprise Server, GitLab or arbitrary Git hosting. Mirror refresh is synchronous, so a large repository can keep the request open. Deleting the Redmine repository removes the local mirror and registration but never deletes the remote GitHub repository.

VCSAdmin Git synchronization fails

Use the complete repository-detail URL ending in /api/v1/scm/repositories/ID, valid Basic Authentication credentials and HTTPS with a trusted certificate. VCSAdmin Git is read-only and remote-only; it intentionally creates no local clone, checkout or mirror.

What does 413 commit_too_large mean?

The affected commit contains more changed files than VCSAdmin permits in one SCM API response. The commonly configured default for scmApi.maxChangedFiles is 1,000, but your VCSAdmin installation may override it. This is a server-side protection, not a missing Redmine table and not a Git clone error.

1. Find the matching VCSAdmin request by its request ID. Version 2.3.5 also logs the sanitized remote repository name, while preserving the stable numeric remote repository ID.
2. Confirm the commit and the effective scmApi.maxChangedFiles value in VCSAdmin.
3. Review memory, API response-size and processing-time impact before raising the limit. Keep Redmine's response and timeout limits consistent with the intended maximum.
4. Run synchronization again. SCM Creator does not silently skip an oversized commit because doing so would make Redmine's imported history incomplete.

Synchronization appears stuck or repeats an error

Open the repository settings and compare the phase, stored cursor, remote head, last successful run and last error. Imports are intentionally bounded, so a large initial history may need several successful scheduled runs. A database lock prevents overlapping synchronization. Upgrades from versions before 2.3 require the plugin migration that creates the synchronization lock table; upgrades from 2.3.4 to 2.3.5 require no new migration.

Repository deletion and data ownership

• Local providers: deletion behavior follows the configured SCM Creator lifecycle and server policy; verify the target path before confirming destructive operations.
• GitHub.com: only the local bare mirror and Redmine registration are removed. The remote repository remains untouched.
• VCSAdmin Git: only the Redmine registration and synchronization state are removed. The remote VCSAdmin repository remains untouched.

What SCM Creator does not provide

The plugin creates or registers repositories for Redmine; it is not a general Git hosting server and does not publish repositories over HTTP, SSH or Subversion DAV. VCSAdmin Git additionally omits write operations, blame, archives, statistics, binary download and arbitrary comparisons because API v1 is deliberately read-only and bounded.