Connect a repository
Connect GitHub or GitLab with one address and one access token, and see at once whether it works.
You connect a repository with one address and one access token, on one screen. Reqursor Development saves the settings in the right order, stores the token, and tests the connection right away. A problem shows up as a sentence you can act on, not as a failed run later.
This page covers GitHub (github.com) and GitLab (gitlab.com and self-managed GitLab). The setup wizard has its own, shorter repository step. This page is about the Connect repository card in Settings, which also checks the tracker side.
What you need
- The address of the repository, as you see it in the browser. Any page of the project works: its home page, a branch, the issues list, or the address you clone from.
- An access token for it. One token does everything: it reads and pushes the code and reads the issues. Which scopes the token needs lists what it takes.
- A role that may change projects and secrets: Owner or Admin.
The three steps
- Open the card
In Settings, Projects & repository, choose the project. The Connect repository card is at the top.
- Paste the address and the token
Choose whether to import issues (on by default) and whether to write results back to the issue (off by default: it adds a comment and a label). If the host is not github.com, gitlab.com or a name that contains
gitlab, the card asks which service it is. - Press Connect
Reqursor Development saves the repository and the ticket source, stores the token, runs the checks and shows each result. When the repository can be read, it copies it to your install and shows the commit it is at.
You can press Test connection at any time to run the checks again. It changes nothing.
The token is write-only. It is never shown again; Settings shows only its last four characters. Moving a project to another host removes the tokens stored for the old one.
Which scopes the token needs
| What you want | GitLab scope | GitHub (classic token) | GitHub (fine-grained token) |
|---|---|---|---|
| Read the code | read_repository | repo | Contents: Read |
| Read the issues | read_api (or api) | repo | Issues: Read |
| Push branches (off by default) | write_repository | repo | Contents: Read and write |
| Write results back to the issue | api | repo | Issues: Read and write |
| Open pull requests on GitHub | repo | Pull requests: Read and write |
The simplest choice on GitLab is a token with api, read_repository and write_repository. On
GitHub it is a classic token with the repo scope. The card has a Create a token in GitLab (or
GitHub) button that opens your host's token page with a name and these scopes already filled in.
Pushing is off by default, so a token that can only read works for everything else.
GitLab
Create a project access token (Settings, Access tokens, in the project) or a personal access token. A project access token is limited to that one project, which is the safer choice. Give it the Developer role if you want it to push.
Paste any address of the project, for example https://gitlab.com/your-group/your-project.
Subgroups work: https://gitlab.com/group/subgroup/project. A [email protected]:group/project.git
address is read too.
GitHub
Create a classic personal access token with the repo scope, or a fine-grained token restricted to
this repository with the access listed in the table above. Paste https://github.com/owner/name or
any page under it.
Only github.com is supported for GitHub. GitHub Enterprise Server is not supported yet.
Self-managed GitLab
Paste the address of a project on your GitLab. A host whose name contains gitlab is recognized
automatically. For any other host name, two cards (GitHub and GitLab, each with its logo) appear
below the address once you paste it. Choose GitLab there.
- If your GitLab runs under a path, such as
https://code.example.com/gitlab, the address is read as it is pasted, so the path is not told apart from a group. Connect first, then open Settings, Integrations, choose Use a different repository and set the GitLab address tohttps://code.example.com/gitlab. The issues check then finds the project. - Use
https://. Plainhttp://is accepted only for an address on a private network, and an install may still refuse it. - The machine running Reqursor Development must be able to reach the host. An address that points to the machine itself, or to a cloud metadata address, is refused.
- The token page of a self-managed GitLab is at
/-/user_settings/personal_access_tokens, or under the project's Settings, Access tokens.
What each check means
Every check runs on its own, so one failing never hides the others. Each shows what was found and, when something is wrong, what to do.
| Check | What it asks | If it fails |
|---|---|---|
| Read the repository | Can the token read the code? | A refused token: create it with the read_repository scope (GitLab) or the repo scope (GitHub), or check the address. Not found: check the address; a private repository also shows as not found when the token cannot see it. Could not reach the host: check the address and that the machine can reach it. |
| Read the issues | Can the token list the project's issues? Skipped when importing issues is off. | Refused: the token expired or was revoked. Not allowed: it needs the api scope (or read_api) on GitLab, repo or Issues read on GitHub. Not found: check the address; on a private project this usually means the token is missing a scope. |
| Push access | May the token push? Informational only. | A warning, not a failure. Pushing is off by default, so it only matters when you switch pushing on. GitHub does not describe fine-grained tokens, so there the answer can be "could not tell". |
| Default branch | Which branch does the repository treat as its default? | A warning when it differs from the project's base branch. Nothing is changed for you; change the base branch in Settings if the project should follow it. |
The connection is ready when the repository can be read and, if you import issues, the issues can be read.
Branch strategy, pushing and pull requests
Under Projects & repository you also choose what happens to a finished change:
- Branch strategy. A branch per ticket (the default) gives every ticket its own branch and its own pull request. One working branch collects every ticket on one branch. See Branch strategy & Autopilot.
- Push branches to the repository. Off by default: a shipped ticket stays a commit in your install's own copy of the repository. On, its branch is pushed to your repository, never to a protected branch. It needs a token that may push.
- Open a pull request for each shipped ticket. A draft pull request into the base branch. It
needs pushing on, the GitHub CLI (
gh) on the machine, and a token that may create pull requests. In the setup wizard, ticking this box turns pushing on for you.
Why one token
A repository and its issues live at the same host, and the same token can be allowed to do both. One token means one place to paste and no strict order to enter things in. Reqursor Development stores the token under both of its names for you. The two uses stay separate inside the product: the git token goes only to the one git process that needs it, and the tracker token only to the issue client, never to the agent.
If you would rather keep them apart, turn Import issues off and connect the tracker separately under Integrations, with a token of its own.
Using the connection for tickets later
If you connected with Import issues off, or pointed the ticket source somewhere else afterwards, you do not need a second token. Under Settings, Integrations, choose GitHub or GitLab as the ticket source: the connected repository is shown as text, and its labels are listed as chips to pick from. Save, then press Use the same connection for tickets. The token you gave when you connected moves, inside your install, to the tracker's name. It is checked against the issues first, so a token without the issue scope is refused with a sentence and nothing is kept. It works only for the repository it was saved for: a ticket source that names another repository is refused. Pasting a different token under Paste a different token stays an option.
If something goes wrong
- "No access token is saved for this repository" when you test a clone: the repository is private and no token is stored for git. Connect it with a token.
- A token was refused: it may have expired, may not be allowed to read the repository, or the address may be wrong. Create a new token and connect again.
- Nothing is pushed: pushing is off by default. Turn on Push branches to the repository.
- Other problems: see Troubleshooting.
- Importing ticketsPull issues from the connected tracker into the queue.
- From zero to your first shipped ticketWhat happens once the repository is connected and a ticket exists.