Differences between revisions 1 and 53 (spanning 52 versions)
Revision 1 as of 2017-08-19 21:24:47
Size: 2180
Editor: ?LarsKruse
Comment: initial documentation
Revision 53 as of 2018-02-03 07:49:51
Size: 12259
Editor: ?formorer
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
{{{#!wiki caution
'''Work in Progress'''

The service described below is not public, yet. Please ignore any related information until it is officially published.

Even the name (''Salsa'') is not official, yet.
}}}
Line 13: Line 5:
Line 18: Line 9:
 * everyone else can register an account with an implicitly added suffix {{{-guest}}}


= Namespace concepts (Users, Teams, Packages, ...) =
 * '''TODO'''


= Permissions =
'''TODO''':
 * Debian Developers
 * everyone else
 * Group Administrators
  * 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 [[https://signup.salsa.debian.org/register/team/|the team registration page]]. There is also a link to it from the [[https://signup.salsa.debian.org/|registration page]]: if you're not logged in yet, you will be asked to do so and be redirected afterwards.

= Projects and Repositories =

A project = a repository.

You can create several projects in the same namespace (user or group).

Debian Developers are able to create projects in the Debian/ Namespace. It's the Salsa equivalent of 'collab-maint' on Alioth, and non-DDs (DMs or external contributors) need to be explicitly granted commit privileges for single projects.

= 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`.<<BR>>
Currently only Push events are supported.

== KGB ==
KGB webhook support is being worked on.

= 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 sourcepackage and chose
either close or tagpending, depending on the action you want to get.

See the code for more details: https://salsa.debian.org/salsa/webhook.
Line 34: Line 78:
Many [[Alioth]] features are (intentionally) not provided by the ''Salsa'' platform. You may want to take a look at the [[Alioth/Sprint/2017/MeetingMinutes|related discussion during a sprint]] for the detailed reasons for this decision. Many [[Alioth]] features are (intentionally) not provided by the ''Salsa'' platform. You may want to take a look at the [[Sprints/2017/Alioth/MeetingMinutes|related discussion during a sprint]] for the detailed reasons for this decision.

{{{#!wiki important
There is significant overlap between this section and the [[Alioth#Deprecation_of_Alioth]] documentation. Those should be merged, somehow. -- TheAnarcat <<DateTime(2017-09-23T18:41:36Z)>>
}}}

== Canonical Repository 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.

== Custom Hooks ==

For security reasons it is not allowed to run arbitrary custom hooks
on repositories. You may want to write yourself a webhook receiver and
put your custom actions into such a one.

Alternatively you may use the common webhook receiver or even enhance
it with new features, see https://salsa.debian.org/salsa/webhook for
details on it.
Line 37: Line 114:
'''TODO'''
This is currently done by hand but Christoph Berg's wrote a handy [[http://www.df7cb.de/blog/2017/Salsa_batch_import.html|batch import script]] that you can use to import your projects semi-automatically.

Once a repository is migrated, you may want to archive the repository on Alioth. One way to do this is to add a pre-receive hook that exits with a non-zero status code, for example:

{{{
$ cat /git/collab-maint/magic-wormhole.git/hooks/pre-receive
#!/bin/sh

cat <<EOF
Repository was moved to Salsa.

https://salsa.debian.org/debian/magic-wormhole

Push refused, this repository was archived. Update your remotes to use the following URL instead:

git@salsa.debian.org:debian/magic-wormhole.git

EOF
exit 1
}}}

Make sure the file is executable (`chmod +x`) and also update the description similarly so the web interface shows the change as well. You can do this automatically with `~hertzog/bin/disable-repository <path-to-git-repo> <name-of-salsa-group>`.

You may also want to add an HTTP redirect from the old repository on Alioth to the new one on Salsa (`git://` and `git+ssh://` cannot be redirected, so you should still make sure to add the pre-receive hook above). You can do this by sending a merge request for [[https://salsa.debian.org/salsa/AliothRewriter|AliothRewriter]].
Line 42: Line 143:
You may want to take a look at the [[Alioth/Sprint/2017/MeetingMinutes/subversion_cvs_bzr_darcs_mercurial|reasons for not supporting other version control systems]] within ''Salsa''.

== Import Mailinglist ==
''Salsa'' does not offer any mailinglist features.

You may want to take a look at the [[Alioth/Sprint/2017/MeetingMinutes/Mailinglist|reasons for not providing mailinglists]] within ''Salsa''.
You may want to take a look at the [[Sprints/2017/Alioth/MeetingMinutes/VCS|reasons for not supporting other version control systems]] within ''Salsa''.

== Import mailing list ==
''Salsa'' does not offer any mailinglist features on its own (see [[Sprints/2017/Alioth/MeetingMinutes/Mailinglists|discussion]]). However, lists previously on alioth can be migrated to a new service retaining the same name @lists.alioth.debian.org; see [[Alioth/MailingListContinuation]] and [[https://lists.debian.org/debian-devel-announce/2018/01/msg00003.html|the announcement]].

Some mailing lists that were formerly hosted on Alioth may be eligible for being hosted on [[https://lists.debian.org|lists.debian.org]]. The lists eligible for migration must follow the requirements outlined on the [[https://www.debian.org/MailingLists/HOWTO_start_list|"How to ask a mailing list" guide]]. The process is also the same as outlined on the guide.

The following kind of lists are probably acceptable for [[https://lists.debian.org|lists.debian.org]]:
 * The list is expected to be useful, to have a purpose and an audience.
 * Public discussion or support lists are probably OK.
 * Commit or bug notifications lists are not OK. You should use the dedicated features of gitlab instead. If you're interested in a package's bug, you're expected to subscribe to it using the [[http://bugs.debian.org/|BTS]] features.

Short version: file a bug on the [[https://bugs.debian.org/lists.debian.org|pseudo-package lists.debian.org]] with the severity 'wishlist', with the following information:
 * List Name
 * Rationale (why do you need this list, stating that you had one on Alioth is not enough!)
 * Short Description (for display in list indices)
 * Long Description (targeted to people that need to decide if they want to join)
 * Category

Lists migrated from Alioth are expected to be open, that is:
 * Open Subscription Policy (no closed lists)
 * Open Post Policy (anybody can post)
 * Open Archive

If you do want the archive and/or the subscribers to be imported into your new mailing list, please:
 * on alioth, using your ssh access, run 'sudo /usr/local/bin/export-list <mailing_list_name>' to get gzipped tar archive (on stdout) containing:
  * mbox file of the archive
 * import the resulting mbox file in your favorite e-mail reader and clean the spam,
 * attach the compressed archive and/or the list of subscribers to your request.

The export only works if the 'Is archive file source for public or private archival?' archive setting is true.

Before any migration ensure that there is consense about the migration and that you have permission from the subscribers. For privacy reasons we expect that the migration process is
done by an admin of the list or the alioth project.

Also, please understand that the requirements and features for lists on lists.debian.org are not the same as for a mailing list on Alioth, and the listmaster might reject your request. Lists.debian.org is not supposed to replace all mailing lists and aliases on Alioth.
Line 52: Line 184:
== Host project web pages ==
Gitlab offer the "Gitlab Pages" feature, and it is enabled on Salsa as '''`http://<namespace>.pages.debian.net/<project>`'''

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

See https://docs.gitlab.com/ce/user/project/pages/index.html for a detailed documentation and HOWTOs.

 * '''''Note:''' there is no SSL for <namespace>.pages.debian.net, since Let's Encrypt doesn't provide wildcard certificates yet.''

Should you want to access the pages with your own domain name and your own certificate, it is possible via ''''Settings > Pages > New Domain'''' in your project.

=== Quick start ===

 1. On your project Home, use '''`Set up CI`''' button
 1. Choose a '''`Gitlab CI Yaml template`''' ('''`Pages`''' templates are at the end)
 1. Edit the template to suit your needs and save it
 1. Push something to the repository. You will see there is a CI Job pending
 1. 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>/)

  * '''''Note:''' 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.''
  * '''''Note 2: 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! ;).''

Salsa Documentation

Salsa is a collaborative development platform within Debian.

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.

Projects and Repositories

A project = a repository.

You can create several projects in the same namespace (user or group).

Debian Developers are able to create projects in the Debian/ Namespace. It's the Salsa equivalent of 'collab-maint' on Alioth, and non-DDs (DMs or external contributors) need to be explicitly granted commit privileges for single projects.

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:

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 webhook support is being worked on.

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 sourcepackage and chose either close or tagpending, depending on the action you want to get.

See the code for more details: https://salsa.debian.org/salsa/webhook.

Hints for previous users of Alioth

Salsa provides services which partially replace some features of the former Alioth service. The following hints may help you to move your packaging collaboration effort from Alioth to Salsa.

Many Alioth features are (intentionally) not provided by the Salsa platform. You may want to take a look at the related discussion during a sprint for the detailed reasons for this decision.

There is significant overlap between this section and the Alioth#Deprecation_of_Alioth documentation. Those should be merged, somehow. -- TheAnarcat 2017-09-23 18:41:36

Canonical Repository 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.

Custom Hooks

For security reasons it is not allowed to run arbitrary custom hooks on repositories. You may want to write yourself a webhook receiver and put your custom actions into such a one.

Alternatively you may use the common webhook receiver or even enhance it with new features, see https://salsa.debian.org/salsa/webhook for details on it.

Import git repository

This is currently done by hand but Christoph Berg's wrote a handy batch import script that you can use to import your projects semi-automatically.

Once a repository is migrated, you may want to archive the repository on Alioth. One way to do this is to add a pre-receive hook that exits with a non-zero status code, for example:

$ cat /git/collab-maint/magic-wormhole.git/hooks/pre-receive 
#!/bin/sh

cat <<EOF
Repository was moved to Salsa.

https://salsa.debian.org/debian/magic-wormhole

Push refused, this repository was archived. Update your remotes to use the following URL instead:

git@salsa.debian.org:debian/magic-wormhole.git

EOF
exit 1

Make sure the file is executable (chmod +x) and also update the description similarly so the web interface shows the change as well. You can do this automatically with ~hertzog/bin/disable-repository <path-to-git-repo> <name-of-salsa-group>.

You may also want to add an HTTP redirect from the old repository on Alioth to the new one on Salsa (git:// and git+ssh:// cannot be redirected, so you should still make sure to add the pre-receive hook above). You can do this by sending a merge request for AliothRewriter.

Import non-git version control repository

Only git repositories are supported by the Salsa platform.

You may want to take a look at the reasons for not supporting other version control systems within Salsa.

Import mailing list

Salsa does not offer any mailinglist features on its own (see discussion). However, lists previously on alioth can be migrated to a new service retaining the same name @lists.alioth.debian.org; see Alioth/MailingListContinuation and the announcement.

Some mailing lists that were formerly hosted on Alioth may be eligible for being hosted on lists.debian.org. The lists eligible for migration must follow the requirements outlined on the "How to ask a mailing list" guide. The process is also the same as outlined on the guide.

The following kind of lists are probably acceptable for lists.debian.org:

  • The list is expected to be useful, to have a purpose and an audience.
  • Public discussion or support lists are probably OK.
  • Commit or bug notifications lists are not OK. You should use the dedicated features of gitlab instead. If you're interested in a package's bug, you're expected to subscribe to it using the BTS features.

Short version: file a bug on the pseudo-package lists.debian.org with the severity 'wishlist', with the following information:

  • List Name
  • Rationale (why do you need this list, stating that you had one on Alioth is not enough!)
  • Short Description (for display in list indices)
  • Long Description (targeted to people that need to decide if they want to join)
  • Category

Lists migrated from Alioth are expected to be open, that is:

  • Open Subscription Policy (no closed lists)
  • Open Post Policy (anybody can post)
  • Open Archive

If you do want the archive and/or the subscribers to be imported into your new mailing list, please:

  • on alioth, using your ssh access, run 'sudo /usr/local/bin/export-list <mailing_list_name>' to get gzipped tar archive (on stdout) containing:

    • mbox file of the archive
  • import the resulting mbox file in your favorite e-mail reader and clean the spam,
  • attach the compressed archive and/or the list of subscribers to your request.

The export only works if the 'Is archive file source for public or private archival?' archive setting is true.

Before any migration ensure that there is consense about the migration and that you have permission from the subscribers. For privacy reasons we expect that the migration process is done by an admin of the list or the alioth project.

Also, please understand that the requirements and features for lists on lists.debian.org are not the same as for a mailing list on Alioth, and the listmaster might reject your request. Lists.debian.org is not supposed to replace all mailing lists and aliases on Alioth.

Import members of a team

It is not possible to transfer the members of an Alioth team to Salsa. You will need to ask the members of your team to join your team on Salsa individually.

Host project web pages

Gitlab offer the "Gitlab Pages" feature, and it is enabled on Salsa as http://<namespace>.pages.debian.net/<project>

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

See https://docs.gitlab.com/ce/user/project/pages/index.html for a detailed documentation and HOWTOs.

  • Note: there is no SSL for <namespace>.pages.debian.net, since Let's Encrypt doesn't provide wildcard certificates yet.

Should you want to access the pages with your own domain name and your own certificate, it is possible via 'Settings > Pages > New Domain' in your project.

Quick start

  1. On your project Home, use Set up CI button

  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://<namespace>.pages.debian.net/<project>/)

    • Note: 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.

    • Note 2: 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.