1. Docs
  2. Resources
  3. Deploys & Repos
  4. Connect a repository

Connect a repository

A repository is the link between your code and the deploy records. This page covers adding one, choosing how it connects, mapping its environments, and changing or deleting it.

6 min read Updated CustomersAdmins

In short

On this page you can

  • Add a repository from GitHub, GitLab, Bitbucket, Azure DevOps, Gitea or any other Git server.
  • Choose Deploy notification only or Connect with token to also read commits.
  • Check a token with Test connection before you save.
  • Map environments, branches and start URLs, and add your own environments such as STAGING.

How to use it

  1. Open Repositories and click Add repository.
  2. Pick the provider, paste the Repository URL and type a Service name.
  3. Choose the connection mode; with a token, click Test connection.
  4. Switch on the environments you deploy to, then click Save.
  5. Copy the deploy token from the window that opens: it is shown only once.

Add a repository#

Any Admin or User with access to the project can add repositories. Admins can also do it from Integrations, where the same Code repositories list appears.

  1. Open the Repositories tab

    Go to Deploys & ReposRepositories and click Add repository. On an empty Overview the same button sits under “No repository connected to this project yet.”

  2. Pick the provider

    GitHub, GitLab, Bitbucket, Azure DevOps, Gitea / Forgejo or Other. Other records deploys only and never reads commits.

  3. Fill in section 1 · Repository

    Paste the Repository URL and type a Service name. Display name and Default branch are optional. See the fields.

  4. Choose section 2 · Connection

    Deploy notification only needs no token. Connect with token also reads commits and changed files. With a token, click Test connection. See Connection modes.

  5. Set section 3 · Environment mapping

    Switch on the environments you deploy this service to. Add a branch and a start URL per environment if you like. See Environment mapping.

  6. Save and copy the deploy token

    Click Save. “Repository saved.” appears and the CI code & deploy token window opens with the new token.

    The repository is listed with the chip No deploy received yet (or Connected with token). Continue with Send deploys from CI.

The deploy token is shown once

Copy it before you close the window. Later the window only shows “Token ending in …abcd is active. It is shown only once.” If you lose it, generate a new one.

The fields#

FieldRequiredRules
ProviderYesGitHub, GitLab, Bitbucket, Azure DevOps, Gitea / Forgejo, Other. Default: GitHub.
Repository URLYesUp to 500 characters, http:// or https://. git@host:owner/repo.git is accepted too. For every provider except Other it must contain owner and repository. Formats.
Service nameYesLowercase letters, digits, - and _, starting with a letter or digit, up to 40 characters. Unique in the project. “Deploys are shown under this name.”
Display nameNoUp to 120 characters. Empty: the last part of the URL, for example web-frontend.
Default branchNoUp to 200 characters. A successful Test connection fills it if it is empty.
Access tokenOnly for Connect with tokenUp to 2,000 characters. Stored encrypted and never shown again.
API base URL (self-hosted)NoUnder Advanced (self-hosted server). See Self-hosted servers.

Repository URL formats#

ProviderExample
GitHub, GitHub Enterprisehttps://github.com/acme/web-frontend
GitLab (subgroups allowed)https://gitlab.com/acme/platform/api
Bitbucket Cloudhttps://bitbucket.org/acme/web-frontend
Azure DevOpshttps://dev.azure.com/acme/Shop/_git/web or https://acme.visualstudio.com/Shop/_git/web
Gitea / Forgejohttps://git.acme.local/acme/web-frontend
OtherAny address; it is stored for reference only.

Connection modes#

ModeWhat you getChip in the list
Deploy notification only“No token needed. CI notifies Smartest after each deploy; you see which version runs where.” No commit list.No deploy received yet until the first deploy, then Webhook only (“Add a token to see commits”).
Connect with tokenEverything above, plus the commits and changed files between two versions. Read-only access is enough.Connected with token (“Commits and diffs are read”).
Provider Other“Commits are not read for this provider; only deploy notifications are recorded.” No token field.No deploy received yet, then Webhook only (“Deploy records only”).

Which token to create#

ProviderToken
GitHubFine-grained token with “Contents: Read” on this repository.
GitLabProject or personal access token with read_api scope.
BitbucketRepository access token, or username:app-password.
Azure DevOpsPersonal access token with Code (Read).
Gitea / ForgejoAccess token with read:repository.

Test connection#

Test connection is active when the URL is filled and a token is typed (or saved). SmartestQA calls the provider’s API once and shows the result under the field.

  • Green: the connection works. The message is followed by the repository’s full name and default branch, for example (acme/web-frontend · main).
  • Red: the server’s reason, such as a rejected token or a repository that was not found. The server writes these messages in Turkish; the troubleshooting page lists each one with its meaning.

Changing the provider, URL, API base URL or token clears the last result. SmartestQA waits up to 10 seconds to connect and 20 seconds for an answer.

Self-hosted servers#

Leave API base URL (self-hosted) empty for github.com, gitlab.com, bitbucket.org and dev.azure.com. For your own server SmartestQA derives the API address from the repository URL:

ProviderDerived API address
GitHub Enterprisehttps://your-host/api/v3
GitLab self-managedhttps://your-host/api/v4
Gitea / Forgejohttps://your-host/api/v1

Set the field only if your API lives elsewhere. The SmartestQA server must reach that address. It refuses loopback and link-local addresses and does not follow redirects. Private network addresses are allowed.

Environment mapping#

Section 3 lists DEV, TEST and PRP, each with a switch, a Branch and a Start URL. “Only the environments switched on are expected for this repository.”

  • Switched off: the cell for that environment shows Not mapped until a deploy arrives there anyway. Deploys are still recorded.
  • Branch (up to 200 characters): for reference, for example develop for DEV and main for PRP. It is shown in the list; deploys from other branches are still recorded.
  • Start URL: pick one of the project’s start page URLs. The list shows the address for that environment. With none defined the list shows “No URL defined”; add them in Start Page URLs.
  • Your own environments: type a name in the field with the placeholder “e.g. STAGING” and click Add environment (or press Enter). Names are turned to upper case: letters, digits, - and _, up to 32 characters. A repository can map at most 12 environments. Your own environments can be removed with the X; DEV, TEST and PRP can only be switched off.

Your own environments get versions, not test results

Pipelines run in DEV, TEST or PRP. A deploy to STAGING is recorded and shown, but its test state is No pipeline environment. See how deploys are matched with runs.

Change or delete a repository#

In the Code repositories list, open the row’s menu (Repository menu, the ⋮ button):

Menu itemWhat it does
SettingsOpens Edit repository · name. The token field is empty with “Leave empty to keep the saved token”. Choosing Deploy notification only and saving removes the saved token.
CI code & deploy tokenWebhook URL, CI code and Generate new token. See Send deploys from CI.
DeleteAsks Delete repository: name: “The repository connection and its deploy token are removed. Past deploy records are kept.” After confirming: “Repository removed.”

If you close the dialog with unsaved changes (X, Esc or a click outside), it asks before discarding them.

Deleting stops CI notifications at once

The deploy token stops working the moment you delete the repository. CI calls then get “invalid deploy token” errors (they do not break the deploy). The repository’s row disappears from Currently running versions; its past records stay in Deploy history.

The repository list#

  • Repository / service: display name, URL and a chip Service: web.
  • Provider and Connection: the chip described in Connection modes.
  • Environment mapping: the switched-on environments with their branch, for example TEST ← release/*.
  • Last deploy: when the last notification arrived, as “12 min ago”. See relative times.

If something goes wrong#

Didn’t find your answer?Write to support with your project name and what you see on screen.

info@smartestqa.ai