Salsa/Doc - Debian Wiki (original) (raw)

Translation(s): English - Português (Brasil)

Contents

  1. Salsa Documentation
  2. Support
  3. Users
    1. Unused accounts for DD before May 2020
  4. Groups
    1. Collaborative Maintenance: "Debian" group
    2. Canonical URLs
  5. Projects and Repositories
  6. Email notifications
  7. Information on manipulating bugs by email
  8. IRC notifications
    1. Irker
    2. KGB
  9. Dealing with Debian BTS from commit messages
  10. Deployment keys
  11. Salsa CI setup
  12. Runners
  13. Web page hosting
  14. Quick start
  15. Getting Help
  16. Hints for previous users of Alioth
  17. API Usage Best practises
  18. SSH Host Keys

Salsa Documentation

Salsa is a collaborative development platform within Debian.

Support

In case you encounter any problems with Salsa, to get support you may want to join us:

... they may help you.

Users

Register an account at https://salsa.debian.org/users/sign_up

Your account will be locked until a gitlab administrator enables it. As of July 2021 you will now receive an email confirming your account validation, please be patient. (Ping the above Support after 4 days patience)

Using your real name when signing up might reduce false positives in the spammer detection heuristics.

Unused accounts for DD before May 2020

Before May 2020 all Debian Developers had accounts created for them using their Debian user name. Accounts that had never been used and never had a password set are deactivated. Those accounts can only be used after being activated properly. Please use any of the support channels. After being reactivated a new password can be set via the password reset.

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.

Collaborative Maintenance: "Debian" group

The debian group is for CollaborativeMaintenance (the old collab-maint on Alioth).

The group is accessible to all Debian developers upon linking their SSO Account, and are granted Maintainer access levels. Direct commits to repositories in the Debian group by any Debian developer are implicitly welcome. No pre-commit coordination (e.g. merge-request or mail) is expected.

External users (non-Debian Developers) need to request write access to repositories inside debian group from a Debian developer they know, or their sponsor. Access should be granted to single projects and not the whole Debian group.

Projects under debian group cannot be transferred or deleted by anyone except Salsa administrators. In case you need to delete a project or have it transferred out into other namespaces, please contact Salsa administrators via support channel. See #Support section for contact information (tickets are preferred example).

Canonical URLs

The canonical URLs for use in debian/control are:

Vcs-Browser: https://salsa.debian.org// Vcs-Git: https://salsa.debian.org//.git

where is

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 → emails 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)).

Take into account that the current implementation sends a single mail per push with all commits lumped together, which makes it rather useless for any post-review workflow. This is tracked upstream at https://gitlab.com/gitlab-org/gitlab-ce/issues/19901.

Information on manipulating bugs by email

GitLab has quite a lot of text commands aka "quick actions" which can be used when interacting with GitLab via email. Most things can be done via email by replying to the email notifications. There are special email addresses for creating new merge requests and issues via email.

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:

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, tina, 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 → Webhooks" 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.

You can ignore a branch or pattern, say wip/*, by providing the ignored-namespaces parameter. See the README in code for more details.

Code: https://salsa.debian.org/salsa/salsa-webhook.

Deployment keys

For automating task FIXME

Salsa CI setup

Salsa can run a whole suite of tests in the GitLab CI/CD functionality. To add this to your project, put recipes/debian.yml@salsa-ci-team/pipeline in CI/CD configuration file in Settings -> CI/CD -> General pipelines (e.g. https://salsa.debian.org/android-tools-team/zipflinger/-/settings/ci_cd#js-general-pipeline-settings). For more info, see https://salsa.debian.org/salsa-ci-team/pipeline#basic-use

Runners

Salsa provides shared runners for all projects to use. All jobs without more specific tags run within a privileged Docker container on one-time-use VM. Outbound connections from the shared runner VMs are limited to http & https.

You may also add group runners for your group or specific runners and configure them for your project.

Configuration files and tools are maintained by the SalsaCI team

Web page hosting

Gitlab offer the "Gitlab Pages" feature, and it is enabled on Salsa as https://.pages.debian.net/

This feature makes use of Gitlab-CI to generate static pages in a public directory, on every push.

See the official documentation for details. Note that hosting pages on arbitrary domains — whilst supported by upstream — is not supported on Salsa due to lack of bandwidth within DSA to support that feature (see RT #7045).

ChrisLamb has created a number of https://lamby.pages.debian.net/salsa-ribbons/ that you can add to your site.

Quick start

  1. On your project Home, use Set up CI/CD button. (If your project is empty, select New file instead.)
  2. Choose a Gitlab CI Yaml template (Pages templates are at the end)
  3. Edit the template to suit your needs and save it
  4. Push something to the repository. You will see there is a CI Job pending
  5. Wait a few minutes for the job to run. When it's Passed you can see your pages at <https://.pages.debian.net//>)

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. ;)

GitLab Pages by default publishes content under public/; if you wish to use another directory, change the `pages:publish` value.

Getting Help

See the Salsa maintenance description.

Hints for previous users of Alioth

See Salsa/AliothMigration.

API Usage Best practises

SSH Host Keys

When connecting to Salsa to fetch or push a Git repo for the first time, it is essential to verify host's ssh keys. The keys for Salsa have been published as SSHFP DNS records as well as in the Debian known_hosts file. This is a one time operation. From now on ssh will trust the keys in the local known_hosts file.

CategoryDeveloper