Connect a GitLab repository by signing in
Create a Borago Board project from a GitLab repository by signing in, with no pasted key, then let a task push a branch and open the merge request.
Borago Board can connect a private GitLab repository without you pasting a key or a token. This tutorial creates a project that way, lets the container clone the code, runs a task that commits on a new branch and pushes it, and ends with the merge request link the app offers after the run.
You will build
A project cloned from GitLab, one task whose branch is pushed, and a link that opens the merge request form with that branch filled in.
You need
- The desktop app with Docker running, see Installing Docker with the app.
- A GitLab account that can add a deploy key to the repository, which means the Maintainer role or higher on that project.
- An API key for one provider, see Choosing an AI provider.
There is no GitHub sign-in. A GitHub repository still works. Paste an SSH private key or a personal access token under Paste a token or key, as described in Connecting a repository.
Steps
1. Start a new project
Press Add project in the board's filter bar. The project dialog opens on the Project Info tab.
Type a Project name. Leave Local path empty for this tutorial, so the code lives in the container.
2. Press Sign in with GitLab
Under Git access, press Sign in with GitLab. A dialog headed Connect a GitLab repository explains what will happen.
Read it, tick I understand a deploy key will be created on the repository I choose., and press Continue to GitLab.
What happens. GitLab asks for the api scope, which is broad. The dialog says so before you go. The app uses the sign-in for two things only, listing your projects and adding one deploy key.
3. Open the link or copy it
A prompt headed Approve in GitLab appears with two buttons, Open with default browser and Copy link, and the link printed beneath. Use Copy link when you are signed in to GitLab in a different browser or profile. The dialog behind it shows a short code and reads Waiting for you to approve. This window updates by itself.
4. Approve in the browser
In GitLab, check that the code on the page matches the one in the app, then approve. Back in the app, the dialog lists the repositories your sign-in can add a key to, with a Filter repositories box. Press the one you want.
What happens. The app creates a key pair and adds the public half to that one repository as a deploy key with write access. It stores the private half encrypted on this machine, exactly like a pasted key, and discards the sign-in. No GitLab token is kept, so there is nothing to renew or sign out of. Git repository URL is filled with the repository's SSH address, and the section reads Connected to followed by the repository and via GitLab, with Disconnect beside it.
5. Tell the agent to leave merging to you
Press Next to reach AI instructions. Global AI instructions is prefilled with a workflow that merges each feature into main. Replace it with this, so the branch waits for your review:
- Create a new branch for each task, named after the task
- Commit your work on that branch with clear commit messages
- Push the branch to origin
- Do not merge into main and do not push main6. Finish the wizard and start the container
Walk the remaining tabs with Next, adding your API key on AI Auth and choosing a Task runner on AI Roles. Press Create project. When asked Start the container now?, press Start container.
What happens. The first start builds the image, which can take a few minutes. Once the container is up, the app clones the repository into it, because the working directory is empty. Until you press Create project, the key is held on this machine for up to 30 minutes. Cancelling the form removes the deploy key from the repository again.
7. Write a task that commits and pushes
Press Add task in the Planning column and paste a small change, adjusted to your repository:
Add a short "Development" section to README.md that explains how to install
the dependencies and run the tests. Keep the rest of the file unchanged.
Commit the change on a new branch and push that branch to origin.Press Add task, then drag the card to To Do. The queue starts it.
What happens. The run gets the stored key in its environment, so git inside the container can push over SSH with no prompt.
8. Open the merge request
When the task reaches Done, open it. An Action comment offers to open a merge request for your branch into the base branch, once the branch is pushed, with a link. Press the link and create the merge request. Then press Complete on the task.
What happens. The link appears only when the run switched branch or committed. It opens GitLab's form with both branches filled in. The base is Git branch when set, otherwise main. The app does not check that the push happened, which is why the note says once the branch is pushed.
Check it worked
The repository's deploy key list in GitLab shows the new key with write access. The branch is on GitLab. The merge request compares it with main.
Where to go next
- To revoke access, delete the deploy key in GitLab.
- Plan a feature with chat, then run the cards turns a larger change into several branches.
Related: Connecting a repository, Creating a project, When the agent asks a question or needs you, Security