Contents
Salsa Documentation
Salsa is a collaborative development platform within Debian.
Support
To get support join us at #alioth@oftc or create an issue in our support tracker.
Users: Login and Registration
Debian Developers can login with their Debian email address
- you need to use your official Debian email address in order to gain specific permissions for Debian Developers
Use password recovery on https://salsa.debian.org/users/sign_in to get a password for your account. Please don't use your Debian password. Salsa has its own password database.
everyone else can register an account with an implicitly added suffix -guest. There is a a self service webfrontend for doing so at https://signup.salsa.debian.org/
Namespace concepts (Users, Teams)
Debian Developers
Debian Developers get synced every 6 hours from LDAP and retain their Debian login as salsa username.
External Users
To avoid clash with the Debian LDAP Usernames, external users get a suffix of -guest to their username.
Groups
Users and Group share the same namespace. To prevent clashes with usernames we enforce groups to a '-team' suffix, with the exception being the 'Debian' group, of which all Debian Developers are members.
To create a group, log in and go to the team registration page. There is also a link to it from the registration page: if you're not logged in yet, you will be asked to do so and be redirected afterwards.
The debian group is for CollaborativeMaintenance (the old collab-maint on Alioth). The group is accessible to all Debian developers by default, who are automatically added with master access levels.
External users need to request access to a Debian developer they know, or their sponsor. Access should be granted to single projects and not the whole Debian group.
Canonical URLS
The canonical URLs for use in debian/control are:
Vcs-Browser: https://salsa.debian.org/<user-or-team>/<package> Vcs-Git: https://salsa.debian.org/<user-or-team>/<package>.git
where <user-or-team> is
alice for DD Alice Developer <alice@debian.org>
bob-guest for non-DD Bob Coder <bobc@example.com>
debian for the Debian/ namespace (the equivalent to collab-maint on alioth)
foobar-team for the Foobar Packaging Team
You can instruct git to rewrite URLs into pushable ssh URLs:
git config --global url."git@salsa.debian.org:".pushInsteadOf "https://salsa.debian.org/"
This will work for all salsa repositories checked out via https:// URLs in the present, past or future.
You can also use a shortcut for all Salsa repositories:
git config --global url."git@salsa.debian.org:".insteadOf salsa:
This way you can use a shorter commandline like this:
git clone salsa:debian/htop
Projects and Repositories
In GitLab, a project is one Git repository, and each Git repository needs a project. You can create several projects in the same namespace (user or group).
Email notifications
Every project owner can enable "email on push". To do so, go the project settings → integrations → project services → email on push and configure the list of recipients you want to send emails to.
In particular, to forward emails to tracker.debian.org, you should add dispatch@tracker.debian.org to the recipients (or, if for some not good reason the project name is not the name of the source package, dispatch+${package}_vcs@tracker.debian.org (where ${package} is the source package name)).
IRC notifications
Irker
Alexander Wirt is sponsoring an Irker instance. It can be enabled with the irker integration available under Settings/Integrations/Irker. Please use the following settings:
- Server host: ruprecht.snow-crash.org
- Server port: 6659
Default IRC URI: irc://irc.oftc.net:6667/
Under recipients add a newline separated list of recipients/channels. If your channel is protected by a key, use the syntax channel-name?key=whatever omitting the leading # sign (failing to omit the # sign will result in Irker joining a channel literally named #channel-name?key=whatever and doing so making your channel key public as it is visible in the bot's /whois.
Currently only Push events are supported.
KGB
KGB supports gitlab webhooks. To use the kgb instances provided by dam, tincho, and gregoa from salsa, set a webhook in your project:
http://kgb.debian.net:9418/webhook/?channel=<irc-channel-name-without-#>
For details, additional parameters, and helper scripts see the KGB documentation at https://salsa.debian.org/kgb-team/kgb/wikis/usage
Dealing with Debian BTS from commit messages
We run a webhook receiver that can modify the Debian BTS based on commit messages. If you want to use it, go to your project, "Settings -> integrations" and add a URL (see below), then click save. No secret token is needed, and currently it only deals with push events.
Possible URLs:
https://webhook.salsa.debian.org/close/SOURCENAME https://webhook.salsa.debian.org/tagpending/SOURCENAME
Replace SOURCENAME with the name of your source package and chose either close or tag pending, depending on the action you want to get.
See the code for more details: https://salsa.debian.org/salsa/webhook.
Deployment keys
For automating task FIXME
Runners
For information about the shared runners, refer to the original salsa announcement:
Bastian (waldi) and Alexander (formorer) added two shared runners, one running on the Google Platform, one on Azure to allow experiments with gitlab-ci. Both runners use docker to provide images. You can use every image available in the official docker registry. If you don't choose an image it defaults to debian:9. We are still looking for some offical sponsors of runners, please contact us at salsa-admin@debian.org if you want to sponsor one.
You may also add specific runners and configure them for your project, here is a list of the runners that are currently available:
Runner Name |
Maintainer |
Purpose |
chuchi |
stapelberg |
TODO |
Running Continuous Integration (CI) tests
Gitlab provides very flexible and full featured CI functionality built in. Using simple YAML files, the Gitlab CI setup will run the scripts in .gitlab-ci.yml in the specified Docker image, and report the results with a full log. This can also be used to build and deploy static websites using "Gitlab Pages", and more.
In your project's "CI/CD Settings" (e.g. https://salsa.debian.org/debian/fdroidserver/settings/ci_cd), set "Custom CI config path" to debian/.gitlab-ci.yml
Create debian/.gitlab-ci.yml and commit it to your project's master branch
For an automated git-buildpackage setup, use the ci-image-git-buildpackage Docker image that is in development, for example:
Web page hosting
Gitlab offer the "Gitlab Pages" feature, and it is enabled on Salsa as https://<namespace>.pages.debian.net/<project>
This feature makes use of Gitlab-CI to generate static pages in a public directory, on every push.
See the official documentation for a details.
https://<namespace>.pages.debian.net should work, thanks to Let's Encrypt new wildcard certificate support.
Quick start
On your project Home, use Set up CI/CD button
Choose a Gitlab CI Yaml template (Pages templates are at the end)
- Edit the template to suit your needs and save it
- Push something to the repository. You will see there is a CI Job pending
Wait a few minutes for the job to run. When it's Passed you can see your pages at https://<namespace>.pages.debian.net/<project>/)
Even though we plan to support simple page generators like Jekyll or Hugo in the future, in most cases, you should content yourself with the HTML template, and generate the pages locally to push them afterward, in order to save the resources on the runner. Some templates might require commands not available on the server anyway.
We mean that. Really. Be nice to the server. At some point in the future we hope to add some dedicated Runners servers - Sponsors welcome!
Getting Help
See the Salsa maintenance description.