Skip to content

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 create in its directory, or velonde::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:

$ git remote add origin https://git.example.com/analytics/sales.git
$ git push -u origin HEAD

Give a colleague access

For a colleague to work on your app, they need two permissions:

  1. 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.
  2. The right to deploy the app, which you give them by listing them under maintainers in velonde.yaml and 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.