Working on an app's code together¶
This page is for people who work on an app with colleagues. It covers getting the code of a deployed app, logging in to your company's git server, and creating a repository for a new project.
Several people work on one app through a git repository. The workspace helps in two places. It knows
where the code of a deployed app lives, so a colleague gets it with one command. It can also
create the repository on your git server when you start a project. Your git server still
decides who may read and change the code, and maintainers in velonde.yaml still decides who may
deploy the app. You arrange both, as described in
Give a colleague access.
Get the code of a deployed app¶
$ velonde clone sales
velonde: cloning https://gitlab.example.com/analytics/sales.git (branch main) into /home/coder/sales
Cloning into '/home/coder/sales'...
velonde: installing the R packages of renv.lock (renv::restore())
...
velonde: the code is in /home/coder/sales
velonde: `velonde deploy` there deploys 'sales'
velonde clone NAME looks up the repository the app was last deployed from and clones it on the
branch that deploy came from. If the app is in a subdirectory of the repository, the command
names that directory. It then installs the packages that renv.lock and uv.lock record. R
runs this step with your own .Rprofile and .Renviron. The repository's own files of that
name run when you open the project. Pass --no-restore to skip the installation, and a second
argument to clone into another directory. In R,
velonde::clone("sales") does the same and then opens the project in RStudio. In RStudio's menu,
File > New Project > New Directory > Code of a deployed workspace app does it too: name the
directory after the app, or give the app's name in the dialog.
Everyone who may open the app can use the command: for an app with access-groups, the
members of those groups, and otherwise everyone on the workspace. The owner, the maintainers and velonde
admins can always use it. The command only tells you where the code is. Whether you can read
it is up to your git server.
The workspace learns the repository from velonde deploy, which records the origin remote of the app's
directory, or from the app's binding to a repository. The command shows who last deployed the
app from that repository, when, and from which commit. If that remote was a personal fork or
the repository has moved since, you see it there. If the app was deployed from a directory
without a remote, the command says so, and you have to ask the owner where the code is. Apps
deployed without git work as before.
velonde clone URL clones any repository and installs its packages in the same way.
Log in to your git server¶
To clone a private repository over https, or to push to it, git needs a token. Create a personal access token on your git server, then run this in a terminal of your IDE:
$ velonde git login
velonde: your personal access token for gitlab.example.com:
velonde: logged in to gitlab.example.com as alice. git clone, pull and push over https use the token in every IDE of yours, and so does your assistant; `velonde git logout gitlab.example.com` removes it
Without an argument the command logs you in to the git server your workspace names. For any other
server, give its address, for example velonde git login https://github.com. The command checks
the token with the server and stores it in your home directory, in
~/.config/velonde/git-credentials, which only you can read. git uses it for that server only, in
all three IDEs. The token never leaves your home directory. Claude Code and Posit Assistant use
it as well when they push for you. velonde git logout removes it. In RStudio, velonde::git_login()
asks for the token in a dialog.
The token needs these scopes:
| Server | To clone and push | To also create repositories |
|---|---|---|
| GitLab | read_repository, write_repository |
api |
| GitHub | A fine-grained token with Contents read and write | A classic token with repo, or a fine-grained one with Administration write on the organisation |
When the token expires or you revoke it, git deletes it from your home directory the next time
the server refuses it. Run velonde git login again with a new one.
Who your commits are by¶
Your commits carry your name and email address, so that your git server shows them as yours.
When your user id on the workspace is an email address, the workspace sets git's identity at the start of
your first session: that address, and the name your identity provider sends in its name
claim. Without one, the name comes from the address (alice.smith@example.com becomes Alice
Smith). velonde git login
replaces it with the name and commit email of your profile on the git server, and says so. If
you set user.name or user.email yourself, the workspace leaves them as they are. To use another
identity, run:
$ git config --global user.name "Alice Smith"
$ git config --global user.email alice.smith@example.com
New repositories start on the branch main.
Create a repository for a new project¶
If your workspace names a git server (git_forge in velonde.env, see the
velonde.env reference), the workspace can create the repository
for you:
- In RStudio, tick Create a repository on the company's git server in File > New Project > New Directory > Velonde project.
- In R, call
velonde::new_app("sales", template = "shiny", repo = TRUE). - For an existing project with at least one commit, run
velonde git createin its directory, orvelonde::git_create()in R.
The workspace creates a private repository with your token in the organisation or group your workspace
names, makes it the project's origin and pushes your commits. --name gives it a name other
than the app's, --group puts it into another group (--group "" puts it into your own
account), and --visibility internal makes it visible to everyone in your organisation. If the
workspace cannot create the repository, for example because the name is taken, the project stays as
it is. If the push fails after the repository was created, push again with
git push -u origin HEAD.
The workspace creates repositories on GitHub and GitLab. On other servers, create the repository there and add it to the project yourself:
Give a colleague access¶
For a colleague to work on your app, they need two permissions:
- Access to the repository, which you give them on your git server. For a repository in your team's group or organisation, they may have it already.
- The right to deploy the app, which you give them by listing them under
maintainersinvelonde.yamland deploying, as Work on an app as a team describes.
The colleague then runs velonde clone <app>, changes the code, commits, pushes and runs
velonde deploy. For an app that is bound to a branch, a push to that branch deploys it.
Pull your colleague's commits with git pull before you deploy yourself, otherwise your deploy
replaces their changes with your version.
A colleague who may read the repository but is not a maintainer can still contribute. They
clone the app, push their change to a branch and open a merge request (a pull request on
GitHub). You review it, merge it and deploy. For a bound app, the merge deploys it. velonde clone
tells them this when they may not deploy the app themselves.