Skip to main content

Connectors

A connector is a single connection to one version control system: one GitLab server, one GitHub organization, one Bitbucket instance. Each connector belongs to a specific Plugin, that is a deployment of the Enterprise Plugin, that actually scans the repositories.

Every Q247 deployment starts with connectors, because without them the platform has no source of commits, and therefore nothing to calculate Calories, Increments or Lines from.

How it works​

The plugin connects to the version control system API, fetches the list of available repositories and clones them locally. The analysis of the code and history takes place entirely on the plugin side. Only the result is sent to Q247.

The path from saving the connector to data on the dashboard has four stages, and each of them takes time:

  1. Repository discovery. The plugin queries the API and reports the found repositories to Q247. This takes 5 to 10 minutes.
  2. Assignment to a project. A manual step, without it scanning does not start.
  3. First scan. Analysis of the entire repository history, from a dozen or so minutes upward, depending on size.
  4. Activating people. A manual step, described in Running the integration. Without it dashboards stay empty.

Scope of processed data​

The source code and the full repository history are cloned and analyzed locally, on the plugin side. They do not leave the infrastructure the plugin runs in: in a standard installation this is the Client's infrastructure (Private Plugin), and in the Cloud Plugin variant it is Q247's infrastructure. The access token also stays on the plugin side, with one exception: in the Generic GIT connector the credentials are part of the repository address, so they reach Q247 together with it.

Only the result of the analysis reaches Q247: the repository address, committer data, the calculated effort vector and calorie score, the model version, and the repository metadata, that is name, address, group and status.

The full technical specification, together with the list of stored fields, is in Enterprise Plugin security.

Prerequisites​

Service account and token​

Authentication uses a personal access token generated on an account that has access to all repositories intended for analysis. This is the most common cause of incomplete results: the connector works, but discovers only part of the repositories, because the service account does not belong to all the groups.

The token needs read-only permissions. In GitLab these correspond to the read_user, read_api and read_repository scopes; in the other systems, their equivalents.

A token with write permission is an unnecessary risk

Q247 never writes anything to the repository. A token with a broader scope than read-only gives no additional function, and it increases the impact of a possible leak.

Credentials from environment variables​

Credentials do not have to be typed directly into the form. Instead of the value you can give the name of an environment variable with the $$ prefix, and the plugin reads it only at the moment it connects to the system.

This works for both fields, the username and the token, independently of each other. So you can give the login explicitly and the token from a variable, or both from variables.

Form fieldValue in the formVariable on the plugin host
Username$$GITLAB_USERGITLAB_USER=q247-service
Personal Access Token (PAT)$$GITLAB_TOKENGITLAB_TOKEN=glpat-xxxxxxxx

The prefix is exactly two dollar signs, followed by the variable name itself, without brackets and without spaces. Writing $GITLAB_TOKEN or ${GITLAB_TOKEN} will not be recognized and will be sent to the system as a literal string.

In that case only the variable name is stored in the Q247 database, not the value itself. The credential stays on the Client's server and does not pass through the form in the browser or through the Q247 backend. Rotating the token then comes down to replacing the variable on the host and restarting the plugin, without going into the panel.

The variable has to exist on the plugin host

This means the machine the plugin runs on. With Cloud Plugin this is the environment on the Q247 side, so setting the variable requires the involvement of the deployment team; with the plugin running at the Client, the variable is set by its infrastructure team.

An unset variable produces no validation error on save. The credential resolves to an empty value and only shows up as failed authentication on the first connection attempt, that is a Failed status on the connector.

The mechanism works in every connector that has username and token fields, that is all of them except Generic GIT, where the credentials are part of the repository URL. It is also supported by the Jira and Confluence integrations, together with the separate Tempo token.

Network access​

The plugin has to reach the version control system API and the Q247 backend. Both connections are outgoing. For repositories added manually in Generic GIT, access has to be public or open for the IP address the given plugin runs from.

Adding a connector​

In Configuration, in the Plugins section, next to the "Connectors" list of the selected deployment, the "+" button shows the list of available types.

Choosing a connector type

Six of the seven types have an identical form. The exception is Generic GIT, which does not connect through an API.

Example connector form (GitLab)

FieldWhat it doesExample
Connector Nameyour own name to recognize it in the listGitLab firmowy
Pluginthe deployment that is to handle this connectorCloud (Europe)
Connector API URLthe address of the version control system APIhttps://gitlab.company.com/api/v4
Usernamethe login of the account the token was generated onq247-service
Personal Access Token (PAT)the service account credentialglpat-xxxxxxxx or $$GITLAB_TOKEN
Organization IDthe organization identifier, only for some typesfirma

The API address is built differently for each system, and this is the most common place for a mistake:

SystemConnector API URL
GitLabhttps://{host}:{port}/api/v4, for example https://gitlab.company.com/api/v4
GitHubthe API address of the instance, a default value for github.com
Azure DevOpshttps://dev.azure.com
Bitbucket, Gitea, Gerritthe API address of the given instance

The Organization ID field does not appear in all types: for Azure DevOps it is required, for GitHub optional, and in the remaining types it is not there at all.

The save button closes the form and starts repository discovery.

Verification and diagnostics​

The Status column in the connector list takes one of six values:

StatusMeaning
Newthe connector is saved, the plugin has not picked it up yet
Pendingthe first connection to the version control system is in progress
Readythe connection is established, repositories not yet processed
Operationalthe connector works and delivers data
Failedthe last connection attempt did not succeed
Archivedthe connector is withdrawn from use, historical data stays

A Pending status lasting longer than a dozen or so minutes means a problem with the connection or the token.

When repositories do not appear in Sources, check in this order:

  1. Whether 5 to 10 minutes have passed and whether you refreshed the page. The list does not update on its own.
  2. Whether the API address is correct, including the suffix proper to the given system. The address of the instance alone, without the API suffix, gives a Failed status.
  3. Whether the token has not expired and whether it has read scopes.
  4. Whether the service account belongs to all the groups whose repositories are to be analyzed. The symptom is an incomplete, not an empty, list.
  5. The plugin logs (q247-plugin.log), which show the API responses and sending errors.

When repositories are visible but dashboards stay empty, the cause almost always lies in one of the two steps described in Running the integration: missing assignment to a project or missing activation of people.

Seven connector types​

See also​