CINXE.COM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="shortcut icon" href="/htdocs/favicon.ico"> <script type="text/javascript" src="/htdocs/bugstatus.js"></script> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> <meta name="robots" content="index,nofollow"> <title>Salsa/Doc - Debian Wiki</title> <script type="text/javascript" src="/htdocs/common/js/common.js"></script> <script type="text/javascript">  </script> <link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="/htdocs/debwiki/css/common.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="screen" href="/htdocs/debwiki/css/screen.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="print" href="/htdocs/debwiki/css/print.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="projection" href="/htdocs/debwiki/css/projection.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="/htdocs/debian-wiki-1.0.css">   <link rel="alternate" title="Debian Wiki: Salsa/Doc" href="/Salsa/Doc?diffs=1&show_att=1&action=rss_rc&unique=0&page=Salsa%2FDoc&ddiffs=1" type="application/rss+xml"> <link rel="Start" href="/FrontPage"> <link rel="Alternate" title="Wiki Markup" href="/Salsa/Doc?action=raw"> <link rel="Alternate" media="print" title="Print View" href="/Salsa/Doc?action=print"> <link rel="Up" href="/Salsa"> <link rel="Search" href="/FindPage"> <link rel="Index" href="/TitleIndex"> <link rel="Glossary" href="/WordIndex"> <link rel="Help" href="/HelpOnFormatting"> </head> <body lang="en" dir="ltr"> <div id="logo"><a href="https://www.debian.org" title="Debian Homepage"><img src="https://www.debian.org/Pics/openlogo-50.png" alt="Debian" width="50" height="61"></a></div> <div id="header"> <div id="wikisection"> <a href="/FrontPage" title="Debian Wiki Homepage">Wiki</a> <div id="username"><a href="/Salsa/Doc?action=login" id="login" rel="nofollow">Login</a></div> </div> <div id="navbar"> <ul id="navibar"> <li class="wikilink"><a href="/FrontPage">FrontPage</a></li><li class="wikilink"><a href="/RecentChanges">RecentChanges</a></li><li class="wikilink"><a href="/FindPage">FindPage</a></li><li class="wikilink"><a href="/HelpContents">HelpContents</a></li><li class="current"><a href="/Salsa/Doc">Salsa/Doc</a></li> </ul> </div> <form id="searchform" method="get" action="/Salsa/Doc"> <div> <input type="hidden" name="action" value="fullsearch"> <input type="hidden" name="context" value="180"> <label for="searchinput">Search:</label> <input id="searchinput" type="text" name="value" value="" size="20" onfocus="searchFocus(this)" onblur="searchBlur(this)" onkeyup="searchChange(this)" onchange="searchChange(this)" alt="Search"> <input id="titlesearch" name="titlesearch" type="submit" value="Titles" alt="Search Titles"> <input id="fullsearch" name="fullsearch" type="submit" value="Text" alt="Search Full Text"> </div> </form> <script type="text/javascript">  </script> <div id="logo"><a href="https://www.debian.org" title="Debian Homepage"><img src="https://www.debian.org/Pics/openlogo-50.png" alt="Debian" width="50" height="61"></a></div> <div id="breadcrumbs"><a href="/FrontPage" title="Debian Wiki Homepage">Wiki</a>/ </div> <ul class="editbar"><li><a href="/Salsa/Doc?action=login" id="login-1" rel="nofollow">Login</a></li><li class="toggleCommentsButton" style="display:none;"><a href="#" class="nbcomment" onClick="toggleComments();return false;">Comments</a></li><li><a class="nbinfo" href="/Salsa/Doc?action=info" rel="nofollow">Info</a></li><li><a class="nbattachments" href="/Salsa/Doc?action=AttachFile" rel="nofollow">Attachments</a></li><li> <form class="actionsmenu" method="GET" action="/Salsa/Doc"> <div> <label>More Actions:</label> <select name="action" onchange="if ((this.selectedIndex != 0) && (this.options[this.selectedIndex].disabled == false)) { this.form.submit(); } this.selectedIndex = 0;"> <option value="raw">Raw Text</option> <option value="print">Print View</option> <option value="RenderAsDocbook">Render as Docbook</option> <option value="refresh">Delete Cache</option> <option value="show" disabled class="disabled">------------------------</option> <option value="SpellCheck">Check Spelling</option> <option value="LikePages">Like Pages</option> <option value="LocalSiteMap">Local Site Map</option> <option value="show" disabled class="disabled">------------------------</option> <option value="RenamePage" disabled class="disabled">Rename Page</option> <option value="DeletePage" disabled class="disabled">Delete Page</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Subscribe User</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Remove Spam</option> <option value="show" disabled class="disabled">Revert to this revision</option> <option value="PackagePages">Package Pages</option> <option value="show" disabled class="disabled">------------------------</option> <option value="Load">Load</option> <option value="Save">Save</option> <option value="SlideShow">SlideShow</option> </select> <input type="submit" value="Do"> </div> <script type="text/javascript">  </script> </form> </li></ul> <h1 id="locationline"> <ul id="pagelocation"> <li><a href="/Salsa">Salsa</a></li><li><a href="/Salsa/Doc">Doc</a></li> </ul> </h1> </div> <div id="page" lang="en" dir="ltr"> <div dir="ltr" id="content" lang="en"> <a href="/DebianWiki/EditorGuide#translation">Translation(s)</a>: <a href="/Salsa/Doc">English</a> - <a href="/pt_BR/Salsa/Doc">Português (Brasil)</a> <hr /> <div class="table-of-contents">Contents<ol><li> <a href="#Salsa_Documentation">Salsa Documentation</a></li><li> <a href="#Support">Support</a></li><li> <a href="#Users">Users</a><ol><li> <a href="#Unused_accounts_for_DD_before_May_2020">Unused accounts for DD before May 2020</a></li></ol></li><li> <a href="#Groups">Groups</a><ol><li> <a href="#Collaborative_Maintenance:_.22Debian.22_group">Collaborative Maintenance: "Debian" group</a></li><li> <a href="#Canonical_URLs">Canonical URLs</a></li></ol></li><li> <a href="#Projects_and_Repositories">Projects and Repositories</a></li><li> <a href="#Email_notifications">Email notifications</a></li><li> <a href="#Information_on_manipulating_bugs_by_email">Information on manipulating bugs by email</a></li><li> <a href="#IRC_notifications">IRC notifications</a><ol><li> <a href="#Irker">Irker</a></li><li> <a href="#KGB">KGB</a></li></ol></li><li> <a href="#Dealing_with_Debian_BTS_from_commit_messages">Dealing with Debian BTS from commit messages</a></li><li> <a href="#Deployment_keys">Deployment keys</a></li><li> <a href="#Salsa_CI_setup">Salsa CI setup</a></li><li> <a href="#Runners">Runners</a></li><li> <a href="#Web_page_hosting">Web page hosting</a><ol><li> <a href="#Quick_start">Quick start</a></li></ol></li><li> <a href="#Getting_Help">Getting Help</a><ol><li> <a href="#Hints_for_previous_users_of_Alioth">Hints for previous users of Alioth</a></li></ol></li><li> <a href="#API_Usage_Best_practises">API Usage Best practises</a></li><li> <a href="#SSH_Host_Keys">SSH Host Keys</a></li></ol></div> <h1 id="Salsa_Documentation">Salsa Documentation</h1> <a href="/Salsa">Salsa</a> is a collaborative development platform within Debian. <h1 id="Support">Support</h1> <div dir="ltr" id="Salsa.2Fsupport.content" lang="en"> In case you encounter any problems with Salsa, to get support you may want to join us: <ul><li>at <a class="ircs" href="ircs://irc.oftc.net/salsa">#salsa on OFTC</a> (<a class="https" href="https://webchat.oftc.net/?channels=salsa">webchat</a>) </li><li>or create an issue in our <a class="https" href="https://salsa.debian.org/salsa/support">support tracker</a> </li><li>or send a mail to <a class="mailto" href="mailto:salsa-admin@debian.org">salsa-admin@debian.org</a>. </li></ul>... they may help you. </div> <h1 id="Users">Users</h1> Register an account at <a class="https" href="https://salsa.debian.org/users/sign_up">https://salsa.debian.org/users/sign_up</a> 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. <h2 id="Unused_accounts_for_DD_before_May_2020">Unused accounts for DD before May 2020</h2> 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 <a href="/Salsa/Doc#Support">support channels</a>. After being reactivated a new password can be set via the <a class="https" href="https://salsa.debian.org/users/password/new">password reset</a>. <h1 id="Groups">Groups</h1> 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 <a class="https" href="https://signup.salsa.debian.org/register/team/">the team registration page</a>. There is also a link to it from the <a class="https" href="https://signup.salsa.debian.org/">registration page</a>: if you're not logged in yet, you will be asked to do so and be redirected afterwards. <h2 id="Collaborative_Maintenance:_.22Debian.22_group">Collaborative Maintenance: "Debian" group</h2> The <tt class="backtick">debian</tt> group is for <a href="/CollaborativeMaintenance">CollaborativeMaintenance</a> (the old <tt class="backtick">collab-maint</tt> on <a href="/Alioth">Alioth</a>). The group is accessible to all Debian developers upon linking their <a class="https" href="https://nm.debian.org/signon/login/">SSO Account</a>, and are granted <tt class="backtick">Maintainer</tt> 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 <tt class="backtick">debian</tt> 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 <tt class="backtick">debian</tt> 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 <a href="/Salsa/Doc#Support">#Support</a> section for contact information (tickets are preferred <a class="https" href="https://salsa.debian.org/salsa/support/-/issues/348">example</a>). <h2 id="Canonical_URLs">Canonical URLs</h2> The canonical URLs for use in <tt class="backtick">debian/control</tt> are: <pre>Vcs-Browser: https://salsa.debian.org/<user-or-team>/<package> Vcs-Git: https://salsa.debian.org/<user-or-team>/<package>.git</pre>where <tt class="backtick"><user-or-team></tt> is <ul><li>alice for a salsa user Alice Developer <<a class="mailto" href="mailto:alice@example.com">alice@example.com</a>> </li><li>debian for the Debian/ namespace (the equivalent to collab-maint on alioth) </li><li>foobar-team for the Foobar Packaging Team </li></ul>You can instruct git to rewrite URLs into pushable ssh URLs: <pre>git config --global url."git@salsa.debian.org:".pushInsteadOf "https://salsa.debian.org/"</pre>This will work for all salsa repositories checked out via <a class="https" href="https://">https://</a> URLs in the present, past or future. You can also use a shortcut for all Salsa repositories: <pre>git config --global url."git@salsa.debian.org:".insteadOf salsa:</pre>This way you can use a shorter commandline like this: <pre>git clone salsa:debian/htop</pre> <h1 id="Projects_and_Repositories">Projects and Repositories</h1> In <a href="/GitLab">GitLab</a>, 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). <h1 id="Email_notifications">Email notifications</h1> 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 <tt class="backtick">dispatch@tracker.debian.org</tt> to the recipients (or, if for some not good reason the project name is not the name of the source package, <tt class="backtick">dispatch+${package}_vcs@tracker.debian.org</tt> (where <tt class="backtick">${package}</tt> 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 <a class="https" href="https://gitlab.com/gitlab-org/gitlab-ce/issues/19901">https://gitlab.com/gitlab-org/gitlab-ce/issues/19901</a>. <h1 id="Information_on_manipulating_bugs_by_email">Information on manipulating bugs by email</h1> <a href="/GitLab">GitLab</a> has quite a lot of <a class="https" href="https://docs.gitlab.com/ee/user/project/quick_actions.html">text commands aka "quick actions"</a> which can be used when interacting with <a href="/GitLab">GitLab</a> via email. Most things can be done via email by replying to the <a class="https" href="https://docs.gitlab.com/ee/workflow/notifications.html">email notifications</a>. There are special email addresses for creating new <a class="https" href="https://docs.gitlab.com/ee/user/project/merge_requests/#create-new-merge-requests-by-email">merge requests</a> and <a class="https" href="https://docs.gitlab.com/ee/user/project/issues/create_issues.html#by-sending-an-email">issues</a> via email. <h1 id="IRC_notifications">IRC notifications</h1> <h2 id="Irker">Irker</h2> 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: <ul><li>Server host: ruprecht.snow-crash.org </li><li>Server port: 6659 </li><li>Default IRC URI: <a class="ircs" href="ircs://irc.oftc.net:6697/">ircs://irc.oftc.net:6697/</a> </li></ul>Under recipients add a newline separated list of recipients/channels. If your channel is protected by a key, use the syntax <tt class="backtick">channel-name?key=whatever</tt> omitting the leading <tt class="backtick">#</tt> sign (failing to omit the <tt class="backtick">#</tt> sign will result in Irker joining a channel literally named <tt class="backtick">#channel-name?key=whatever</tt> and doing so making your channel key public as it is visible in the bot's <tt class="backtick">/whois</tt>. Currently only Push events are supported. <h2 id="KGB">KGB</h2> KGB supports gitlab webhooks. To use the kgb instances provided by dam, tina, and gregoa from salsa, set a webhook in your project: <tt>http://kgb.debian.net:9418/webhook/?channel=<irc-channel-name-without-#></tt> For details, additional parameters, and helper scripts see the KGB documentation at <a class="https" href="https://salsa.debian.org/kgb-team/kgb/wikis/usage">https://salsa.debian.org/kgb-team/kgb/wikis/usage</a> <h1 id="Dealing_with_Debian_BTS_from_commit_messages">Dealing with Debian BTS from commit messages</h1> 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: <pre>https://webhook.salsa.debian.org/close/SOURCENAME https://webhook.salsa.debian.org/tagpending/SOURCENAME</pre>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: <a class="https" href="https://salsa.debian.org/salsa/salsa-webhook">https://salsa.debian.org/salsa/salsa-webhook</a>. <h1 id="Deployment_keys">Deployment keys</h1> For automating task FIXME <h1 id="Salsa_CI_setup">Salsa CI setup</h1> Salsa can run a whole suite of tests in the <a href="/GitLab">GitLab</a> CI/CD functionality. To add this to your project, put <tt class="backtick">recipes/debian.yml@salsa-ci-team/pipeline</tt> in CI/CD configuration file in Settings -> CI/CD -> General pipelines (e.g. <a class="https" href="https://salsa.debian.org/android-tools-team/zipflinger/-/settings/ci_cd#js-general-pipeline-settings">https://salsa.debian.org/android-tools-team/zipflinger/-/settings/ci_cd#js-general-pipeline-settings</a>). For more info, see <a class="https" href="https://salsa.debian.org/salsa-ci-team/pipeline#basic-use">https://salsa.debian.org/salsa-ci-team/pipeline#basic-use</a> <h1 id="Runners">Runners</h1> Salsa provides <a class="https" href="https://docs.gitlab.com/ce/ci/runners/#shared-specific-and-group-runners">shared runners</a> 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 <a href="/Teams/SalsaCI">SalsaCI team</a> <h1 id="Web_page_hosting">Web page hosting</h1> Gitlab offer the "Gitlab Pages" feature, and it is enabled on Salsa as <tt class="backtick">https://<namespace>.pages.debian.net/<project></tt> This feature makes use of Gitlab-CI to generate static pages in a <tt class="backtick">public</tt> directory, on every push. See <a class="https" href="https://docs.gitlab.com/ce/user/project/pages/">the official documentation</a> for details. Note that hosting pages on arbitrary domains — whilst <a class="https" href="https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html">supported by upstream</a> — is not supported on Salsa due to lack of bandwidth within <a href="/Teams/DSA">DSA</a> to support that feature (see <a class="https" href="https://rt.debian.org/Ticket/Display.html?id=7045">RT #7045</a>). <a href="/ChrisLamb">ChrisLamb</a> has created a number of <a class="https" href="https://lamby.pages.debian.net/salsa-ribbons/">https://lamby.pages.debian.net/salsa-ribbons/</a> that you can add to your site. <div class="note"><a class="https" href="https://<namespace>.pages.debian.net">https://<namespace>.pages.debian.net</a> should work, thanks to Let's Encrypt new <a class="https" href="https://letsencrypt.org/2017/07/06/wildcard-certificates-coming-jan-2018.html">wildcard certificate support</a>. </div> <h2 id="Quick_start">Quick start</h2> <ol type="1"><li>On your project Home, use <tt class="backtick">Set up CI/CD</tt> button. (If your project is empty, select <tt class="backtick">New file</tt> instead.) </li><li>Choose a <tt class="backtick">Gitlab CI Yaml template</tt> (<tt class="backtick">Pages</tt> templates are at the end) </li><li>Edit the template to suit your needs and save it </li><li>Push something to the repository. You will see there is a CI Job pending </li><li>Wait a few minutes for the job to run. When it's <tt class="backtick">Passed</tt> you can see your pages at <a class="https" href="https://<namespace>.pages.debian.net/<project>/">https://<namespace>.pages.debian.net/<project>/</a>) </li></ol><div class="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 <tt class="backtick">HTML</tt> 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. </div><div class="important">We mean that. Really. Be nice to the server. <img alt=";)" height="16" src="/htdocs/debwiki/img/smile4.png" title=";)" width="16" /> </div><a href="/GitLab">GitLab</a> Pages by default publishes content under <tt class="backtick">public/</tt>; if you wish to use another directory, change the <a class="https" href="https://salsa.debian.org/help/ci/yaml/index.md#pagespublish">`pages:publish`</a> value. <h1 id="Getting_Help">Getting Help</h1> See the <a href="/Salsa#Maintenance">Salsa maintenance</a> description. <h2 id="Hints_for_previous_users_of_Alioth">Hints for previous users of Alioth</h2> See <a href="/Salsa/AliothMigration">Salsa/AliothMigration</a>. <h1 id="API_Usage_Best_practises">API Usage Best practises</h1> <ul><li>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. </li><li>do not search for getting an id. If you need the id, access the project by name and use path-encoding <a class="https" href="https://docs.gitlab.com/ee/api/#namespaced-path-encoding">https://docs.gitlab.com/ee/api/#namespaced-path-encoding</a> </li><li>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 (<a class="https" href="https://docs.gitlab.com/ee/api/groups.html#list-a-group-s-projects">https://docs.gitlab.com/ee/api/groups.html#list-a-group-s-projects</a>). </li><li>Implement proper pagination, please do not just requests a few hundreds elements per page </li><li>set an <tt class="backtick">User-Agent</tt> header with information about the project; don't make requests with generic user agent headers </li><li>if you use a lib, ensure the lib does implement the api properly </li><li>do not run extensive jobs too often </li><li>please consider to use vcswatch or other data gathering projects </li><li>do not regularly poll things </li><li>if in doubt, talk to us before you code and talk to us before you put your code into production </li></ul> <h1 id="SSH_Host_Keys">SSH Host Keys</h1> When connecting to Salsa to fetch or push a Git repo for the first time, it is essential to verify host's <tt class="backtick">ssh</tt> keys. The keys for Salsa have been published as SSHFP DNS records as well as in the Debian <a class="https" href="https://db.debian.org/debian_known_hosts">known_hosts</a> file. This is a one time operation. From now on ssh will trust the keys in the local <tt class="backtick">known_hosts</tt> file. <hr /> <a href="/CategoryDeveloper">CategoryDeveloper</a> </div><div id="pagebottom"></div> </div> <div id="footer"> Salsa/Doc (<a class="nbinfo" href="/Salsa/Doc?action=info" rel="nofollow">last modified 2024-09-04 03:57:56</a>) <ul id="credits"> <li>Debian <a href="https://www.debian.org/legal/privacy">privacy policy</a>, Wiki <a href="/Teams/DebianWiki">team</a>, <a href="https://bugs.debian.org/wiki.debian.org">bugs</a> and <a href="https://salsa.debian.org/debian/wiki.debian.org">config</a>.</li><li>Powered by <a href="https://moinmo.in/" title="This site uses the MoinMoin Wiki software.">MoinMoin</a> and <a href="https://moinmo.in/Python" title="MoinMoin is written in Python.">Python</a>, with hosting provided by <a href="https://www.man-da.de/">Metropolitan Area Network Darmstadt</a>.</li> </ul> </div> </body> </html>