Differences between revisions 1 and 110 (spanning 109 versions)
Revision 1 as of 2017-08-19 21:24:47
Size: 2180
Editor: ?LarsKruse
Comment: initial documentation
Revision 110 as of 2018-10-25 13:57:26
Size: 13689
Editor: lamby
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 14: Line 6:
= Support =
<<Include(Salsa/support)>>
Line 16: Line 10:
Line 18: Line 13:
 * 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

= 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 [[Alioth/Sprint/2017/MeetingMinutes|related discussion during a sprint]] for the detailed reasons for this decision.

== Import git repository ==
'''TODO'''

== Import non-git version control repository ==
Only git repositories are supported by the ''Salsa'' platform.

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''.

== 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.
  * 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.

=== Collaborative Maintenance: "Debian" group ===

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 `Maintainer` access levels.

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 Alioth administrators via support channel. See [[#Support]] section for contact information.

== 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 → 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 [[https://docs.gitlab.com/ee/user/project/quick_actions.html|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 [[https://docs.gitlab.com/ee/workflow/notifications.html|email notifications]]. There are special email addresses for creating new [[https://docs.gitlab.com/ee/user/project/merge_requests/#create-new-merge-requests-by-email|merge requests]] and [[https://docs.gitlab.com/ee/user/project/issues/create_new_issue.html#new-issue-via-email|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:

 * Server host: ruprecht.snow-crash.org
 * Server port: 6659
 * Default IRC URI: ircs://irc.oftc.net:6697/

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

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/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:

||<tablestyle="border: 1">'''Runner Name'''||'''Maintainer'''||'''Purpose'''||
||chuchi ||stapelberg || TODO ||


= Running Continuous Integration (CI) tests =

Gitlab provides very flexible and full featured CI functionality built in. Using [[https://docs.gitlab.com/ce/ci/yaml/|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. The ''salsa-ci-team'' provides standard Docker images to automate the whole process as much as possible.

 1. 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''
 2. Create ''debian/gitlab-ci.yml'' and commit it to your project's ''master'' branch
 3. One approach is using the following pipeline https://salsa.debian.org/salsa-ci-team/pipeline/ covers ''git-buildpackage, autopkgtest, reprotest, piuparts'' and ''lintian''. It requires adding its bot user as a ''Developer'' to the project.
 4. The [[https://salsa.debian.org/salsa-ci-team/ci-image-git-buildpackage|ci-image-git-buildpackage]] image is configured by manually editing ''debian/.gitlab-ci.yml''. It runs ''git-buildpackage'', ''lintian'', ''autopkgtest'', and ''aptly'', with more tools on the way:

{{{#!highlight yaml
image: registry.salsa.debian.org/salsa-ci-team/ci-image-git-buildpackage:latest

build:
  artifacts:
    paths:
    - "*.deb"
    expire_in: 1 day
  script:
    - gitlab-ci-git-buildpackage-all
}}}

If you want the build result to be posted to an apt repo, then use the ''aptly'' script. It'll be posted to an unsigned repo on pages.debian.net. For example, https://salsa.debian.org/foo/bar will be posted to https://foo.pages.debian.net/bar.

{{{#!highlight yaml
image: registry.salsa.debian.org/salsa-ci-team/ci-image-git-buildpackage:latest

pages:
  stage: deploy
  artifacts:
    paths:
      - public
  script:
    - gitlab-ci-git-buildpackage-all
    - gitlab-ci-aptly
}}}

It is also possible to run each step manually or even split them into separate GitLab CI "Jobs":

{{{#!highlight yaml
image: registry.salsa.debian.org/salsa-ci-team/ci-image-git-buildpackage:latest

pages:
  stage: deploy
  artifacts:
    paths:
      - public
  script:
    - gitlab-ci-enable-experimental
    - gitlab-ci-git-buildpackage
    - gitlab-ci-lintian
    - gitlab-ci-autopkgtest
    - gitlab-ci-aptly
}}}


There is a more basic setup based on building with `dpkg-buildpackage` as documented on the Gitlab blog: [[https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/|Automated Debian Package Build with GitLab CI]]

= 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 [[https://docs.gitlab.com/ce/user/project/pages/|the official documentation]] for details.

[[ChrisLamb]] has created a number of [[https://lamby.pages.debian.net/salsa-ribbons/||Github-esque "fork me on Salsa" image ribbons]] that you can add to your site.

{{{#!wiki note
https://<namespace>.pages.debian.net should work, thanks to Let's Encrypt new [[https://letsencrypt.org/2017/07/06/wildcard-certificates-coming-jan-2018.html|wildcard certificate support]].
}}}

== Quick start ==

 1. On your project Home, use '''`Set up CI/CD`''' button. (If your project is empty, select '''`New file`''' instead.)
 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>/)

{{{#!wiki important
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.
}}}

{{{#!wiki important
'''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! ;)
}}}

'''important''': (at least for static pages deployment) your artifacts must be stored in a directory named `public/`; if they are currently in a different location, use the `script` section in `.gitlab-ci.yml` to create that dir and copy the content there.
Line 54: Line 241:

== Hints for previous users of Alioth ==

See [[Salsa/AliothMigration]].

= API Usage Best practises =

 * if you want to know if a project exists, access the project by name, authenticated, if you get a 404 then it doesn't exists.
 * do not search for getting an id. If you need the id, access the project by name and use path-encoding https://docs.gitlab.com/ee/api/#namespaced-path-encoding
 * do not request all projects in a group unless you really have. If you really have to get the list, for i.e. looping, use simple=true (https://docs.gitlab.com/ee/api/groups.html#list-a-group-s-projects).
 * Implement proper pagination, please do not just requests a few hundreds elements per page
 * if you use a lib, ensure the lib does implement the api properly
 * do not run extensive jobs too often
 * please consider to use vcswatch or other data gathering projects
 * do not regularly poll things
 * if in doubt, talk to us before you code and talk to us before you put your code into production

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

Collaborative Maintenance: "Debian" group

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 Maintainer access levels.

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 Alioth administrators via support channel. See #Support section for contact information.

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 → 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, 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.

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/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. The salsa-ci-team provides standard Docker images to automate the whole process as much as possible.

  1. 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

  2. Create debian/gitlab-ci.yml and commit it to your project's master branch

  3. One approach is using the following pipeline https://salsa.debian.org/salsa-ci-team/pipeline/ covers git-buildpackage, autopkgtest, reprotest, piuparts and lintian. It requires adding its bot user as a Developer to the project.

  4. The ci-image-git-buildpackage image is configured by manually editing debian/.gitlab-ci.yml. It runs git-buildpackage, lintian, autopkgtest, and aptly, with more tools on the way:

   1 image: registry.salsa.debian.org/salsa-ci-team/ci-image-git-buildpackage:latest
   2 
   3 build:
   4   artifacts:
   5     paths:
   6     - "*.deb"
   7     expire_in: 1 day
   8   script:
   9     - gitlab-ci-git-buildpackage-all

If you want the build result to be posted to an apt repo, then use the aptly script. It'll be posted to an unsigned repo on pages.debian.net. For example, https://salsa.debian.org/foo/bar will be posted to https://foo.pages.debian.net/bar.

   1 image: registry.salsa.debian.org/salsa-ci-team/ci-image-git-buildpackage:latest
   2 
   3 pages:
   4   stage: deploy
   5   artifacts:
   6     paths:
   7       - public
   8   script:
   9     - gitlab-ci-git-buildpackage-all
  10     - gitlab-ci-aptly

It is also possible to run each step manually or even split them into separate GitLab CI "Jobs":

   1 image: registry.salsa.debian.org/salsa-ci-team/ci-image-git-buildpackage:latest
   2 
   3 pages:
   4   stage: deploy
   5   artifacts:
   6     paths:
   7       - public
   8   script:
   9     - gitlab-ci-enable-experimental
  10     - gitlab-ci-git-buildpackage
  11     - gitlab-ci-lintian
  12     - gitlab-ci-autopkgtest
  13     - gitlab-ci-aptly

There is a more basic setup based on building with dpkg-buildpackage as documented on the Gitlab blog: Automated Debian Package Build with GitLab CI

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 details.

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

https://<namespace>.pages.debian.net should work, thanks to Let's Encrypt new wildcard certificate support.

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://<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! ;)

important: (at least for static pages deployment) your artifacts must be stored in a directory named public/; if they are currently in a different location, use the script section in .gitlab-ci.yml to create that dir and copy the content there.

Getting Help

See the Salsa maintenance description.

Hints for previous users of Alioth

See Salsa/AliothMigration.

API Usage Best practises

  • if you want to know if a project exists, access the project by name, authenticated, if you get a 404 then it doesn't exists.
  • do not search for getting an id. If you need the id, access the project by name and use path-encoding https://docs.gitlab.com/ee/api/#namespaced-path-encoding

  • do not request all projects in a group unless you really have. If you really have to get the list, for i.e. looping, use simple=true (https://docs.gitlab.com/ee/api/groups.html#list-a-group-s-projects).

  • Implement proper pagination, please do not just requests a few hundreds elements per page
  • if you use a lib, ensure the lib does implement the api properly
  • do not run extensive jobs too often
  • please consider to use vcswatch or other data gathering projects
  • do not regularly poll things
  • if in doubt, talk to us before you code and talk to us before you put your code into production