1SALSA(1)                                                              SALSA(1)
2
3
4

NAME

6       salsa - tool to manipulate salsa repositories and group members
7

SYNOPSIS

9         # salsa <command> <args>
10         salsa whoami
11         salsa search_project devscripts
12         salsa search_project qa/qa
13         salsa search_group js-team
14         salsa search_group perl-team/modules
15         salsa search_user yadd
16         salsa push_repo . --group js-team --kgb --irc devscripts --tagpending
17         salsa update_repo node-mongodb --group js-team --disable-kgb --desc \
18               --desc-pattern "Package %p"
19         salsa update_repo js-team/node-mongodb --kgb --irc debian-js
20         salsa update_safe --all --desc --desc-pattern "Debian package %p" \
21               --group js-team
22         salsa checkout node-mongodb --group js-team
23         salsa checkout js-team/node-mongodb
24         salsa add_user developer foobar --group-id 2665
25         salsa update_user maintainer foobar --group js-team
26         salsa del_user foobar --group js-team
27         salsa last_ci_status js-team/nodejs
28

DESCRIPTION

30       salsa is a designed to create and configure repositories on
31       <https://salsa.debian.org> and manage users of groups.
32
33       A Salsa token is required, except for search* commands, and must be set
34       in command line (see below), or in your configuration file
35       (~/.devscripts):
36
37         SALSA_TOKEN=abcdefghi
38
39       or
40
41         SALSA_TOKEN=`cat ~/.token`
42
43       or
44
45         SALSA_TOKEN_FILE=~/.dpt.conf
46
47       If you choose to link another file using SALSA_TOKEN_FILE, it must
48       contain a line with one of (no differences):
49
50         <anything>SALSA_PRIVATE_TOKEN=xxxx
51         <anything>SALSA_TOKEN=xxxx
52
53       This allows for example to use dpt(1) configuration file (~/.dpt.conf)
54       which contains:
55
56         DPT_SALSA_PRIVATE_TOKEN=abcdefghi
57

COMMANDS

59   Managing users and groups
60       join
61           Request access to a group.
62
63             salsa join js-team
64             salsa join --group js-team
65             salsa join --group-id 1234
66
67       add_user
68           Add a user to a group.
69
70             salsa --group js-group add_user guest foouser
71             salsa --group-id 1234 add_user guest foouser
72             salsa --group-id 1234 add_user maintainer 1245
73
74           First argument is the GitLab's access levels: guest, reporter,
75           developer, maintainer, owner.
76
77       del_user
78           Remove a user from a group
79
80             salsa --group js-team del_user foouser
81             salsa --group-id=1234 del_user foouser
82
83       list_groups
84           List sub groups of current one if group is set, groups of current
85           user else.
86
87       group
88           Show group members.
89
90             salsa --group js-team group
91             salsa --group-id 1234 group
92
93       search_group
94           Search for a group using given string. Shows group id and other
95           information.
96
97             salsa search_group perl-team
98             salsa search_group perl-team/modules
99             salsa search_group 2666
100
101       search_user
102           Search for a user using given string. Shows user id and other
103           information.
104
105             salsa search_user yadd
106
107       update_user
108           Update user role in a group.
109
110             salsa --group-id 1234 update_user guest foouser
111             salsa --group js-team update_user maintainer 1245
112
113           First argument is the GitLab's access levels: guest, reporter,
114           developer, maintainer, owner.
115
116       whoami
117           Gives information on the token owner
118
119             salsa whoami
120
121   Managing repositories
122       One of "--group", "--group-id", "--user" or "--user-id" is required to
123       manage repositories. If both are set, salsa warns and only
124       "--user"/"--user-id" is used. If none is given, salsa uses current user
125       id (token owner).
126
127       check_repo
128           Verify that repo(s) are well configured. It works exactly like
129           update_repo except that it does not modify anything but just lists
130           projects not well configured with found errors.
131
132             salsa --user yadd --tagpending --kgb --irc=devscripts check_repo test
133             salsa --group js-team check_repo --all
134             salsa --group js-team --rename-head check_repo test1 test2 test3
135
136       checkout or co
137           Clone repo in current dir. If directory already exists, update
138           local repo.
139
140             salsa --user yadd co devscripts
141             salsa --group js-team co node-mongodb
142             salsa co js-team/node-mongodb
143
144           You can clone more than one repository or all repositories of a
145           group or a user:
146
147             salsa --user yadd co devscripts autodep8
148             salsa co yadd/devscripts js-team/npm
149             salsa --group js-team co --all           # All js-team repos
150             salsa co --all                           # All your repos
151
152       create_repo
153           Create public empty project. If "--group"/"--group-id" is set,
154           project is created in group directory, else in user directory.
155
156             salsa --user yadd create_repo test
157             salsa --group js-team --kgb --irc-channel=devscripts create_repo test
158
159       del_repo
160           Delete a repository.
161
162       fork
163           Forks a project in group/user repository and set "upstream" to
164           original project. Example:
165
166             $ salsa fork js-team/node-mongodb --verbose
167             ...
168             salsa.pl info: node-mongodb ready in node-mongodb/
169             $ cd node-mongodb
170             $ git remote --verbose show
171             origin          git@salsa.debian.org:me/node-mongodb (fetch)
172             origin          git@salsa.debian.org:me/node-mongodb (push)
173             upstream        git@salsa.debian.org:js-team/node-mongodb (fetch)
174             upstream        git@salsa.debian.org:js-team/node-mongodb (push)
175
176           For a group:
177
178             salsa fork --group js-team user/node-foo
179
180       forks
181           List forks of project(s).
182
183             salsa forks qa/qa debian/devscripts
184
185           Project can be set using full path or using --group/--group-id or
186           --user/--user-id, else it is searched in current user namespace.
187
188       push
189           Push relevant packaging refs to origin Git remote. To be run from
190           packaging working directory.
191
192             salsa push
193
194           It pushes the following refs to the configured remote for the
195           debian-branch or, falling back, to the "origin" remote:
196
197           "master" branch (or whatever is set to debian-branch in gbp.conf)
198           "upstream" branch (or whatever is set to upstream-branch in
199           gbp.conf)
200           "pristine-tar" branch
201           tags named "debian/*" (or whatever is set to debian-tag in
202           gbp.conf)
203           tags named "upstream/*" (or whatever is set to upstream-tag in
204           gbp.conf)
205           all tags, if the package's source format is "3.0 (native)"
206       ls or list_repos
207           Shows projects owned by user or group. If second argument exists,
208           search only matching projects
209
210             salsa --group js-team list_repos
211             salsa --user yadd list_repos foo*
212
213       last_ci_status or ci
214           Displays last continuous integration result. Use --verbose to see
215           URL of pipeline when result isn't success. Unless --no-fail is set,
216           salsa last_ci_status will stop on first "failed" status.
217
218             salsa --group js-team last_ci_status --all --no-fail
219             salsa --user yadd last_ci_status foo
220             salsa last_ci_status js-team/nodejs
221
222           This commands returns the number of "failed" status found.
223           "success" entries are displayed using STDOUT while other are
224           displayed (with details) using STDERR. Then you can easily see only
225           failures using:
226
227             salsa --group js-team last_ci_status --all --no-fail >/dev/null
228
229       merge_request, mr
230           Creates a merge request.
231
232           Suppose you created a fork using salsa fork, modify some things in
233           a new branch using one commit and want to propose it to original
234           project (branch "master"). You just have to launch this in source
235           directory:
236
237             salsa mr
238
239           Other example:
240
241             salsa mr --mr-dst-project debian/foo --mr-dst-branch debian/master
242
243           or simply
244
245             salsa mr debian/foo debian/master
246
247           Note that unless destination project has been set using command
248           line, salsa merge_request will search it in the following order:
249
250           using GitLab API: salsa will detect from where this project was
251           forked
252           using "upstream" origin
253           else salsa will use source project as destination project
254
255           To force salsa to use source project as destination project, you
256           can use "same":
257
258             salsa mr --mr-dst-project same
259             # or
260             salsa mr same
261
262           New merge request will be created using last commit title and
263           description.
264
265           See --mr-* options for more.
266
267       merge_requests, mrs
268           List opened merge requests for project(s)
269
270             salsa mrs qa/qa debian/devscripts
271
272           Project can be set using full path or using --group/--group-id or
273           --user/--user-id, else it is searched in current user namespace.
274
275       protect_branch
276           Protect/unprotect a branch.
277
278           Set protection
279                 #                                    project      branch merge push
280                 salsa --group js-team protect_branch node-mongodb master m     d
281
282               "merge" and "push" can be one of:
283
284               o, owner: owner only
285               m, maintainer: o + maintainers allowed
286               d, developer: m + developers allowed
287               r, reporter: d + reporters allowed
288               g, guest: r + guest allowed
289           Unprotect
290                 salsa --group js-team protect_branch node-mongodb master no
291
292       protected_branches
293           List protected branches
294
295             salsa --group js-team protected_branches node-mongodb
296
297       push_repo
298           Create a new project from a local Debian source directory
299           configured with git.
300
301           push_repo executes the following steps:
302
303           gets project name using debian/changelog file;
304           launches git remote add upstream ...;
305           launches create_repo;
306           pushes local repo.
307
308           Examples:
309
310             salsa --user yadd push_repo ./test
311             salsa --group js-team --kgb --irc-channel=devscripts push_repo .
312
313       rename_branch
314           Rename branch given in --source-branch with name given in
315           --dest-branch.  You can use --no-fail and --all options here.
316
317       search, search_project, search_repo
318           Search for a project using given string. Shows name, owner id and
319           other information.
320
321             salsa search devscripts
322             salsa search debian/devscripts
323             salsa search 18475
324
325       update_repo
326           Configure repo(s) using parameters given to command line.  A repo
327           name has to be given unless --all is set. Prefer to use
328           update_safe.
329
330             salsa --user yadd --tagpending --kgb --irc=devscripts update_repo test
331             salsa --group js-team update_repo --all
332             salsa --group js-team --rename-head update_repo test1 test2 test3
333             salsa update_repo js-team/node-mongodb --kgb --irc debian-js
334
335           By default when using --all, salsa will fail on first error. If you
336           want to continue, set --no-fail. In this case, salsa will display a
337           warning for each project that has fail but continue with next
338           project. Then to see full errors, set --verbose.
339
340       update_safe
341           Launch check_repo and ask before launching update_repo (unless
342           --yes).
343
344             salsa --user yadd --tagpending --kgb --irc=devscripts update_safe test
345             salsa --group js-team update_safe --all
346             salsa --group js-team --rename-head update_safe test1 test2 test3
347             salsa update_safe js-team/node-mongodb --kgb --irc debian-js
348
349   Other
350       purge_cache
351           Empty local cache.
352

OPTIONS

354   General options
355       -C, --chdir
356           Change directory before launching command
357
358             salsa -C ~/debian co debian/libapache2-mod-fcgid
359
360       --cache-file
361           File to store cached values. Default to ~/.cache/salsa.json. An
362           empty value disables cache.
363
364           ".devscripts" value: SALSA_CACHE_FILE
365
366       --no-cache
367           Disable cache usage. Same as --cache-file ''
368
369       --conffile, --conf-file
370           Add or replace default configuration files ("/etc/devscripts.conf"
371           and "~/.devscripts"). This can only be used as the first option
372           given on the command-line.
373
374           replace:
375                 salsa --conf-file test.conf <command>...
376                 salsa --conf-file test.conf --conf-file test2.conf  <command>...
377
378           add:
379                 salsa --conf-file +test.conf <command>...
380                 salsa --conf-file +test.conf --conf-file +test2.conf  <command>...
381
382               If one --conf-file has no "+", default configuration files are
383               ignored.
384
385       --no-conf, --noconf
386           Don't read any configuration files. This can only be used as the
387           first option given on the command-line.
388
389       --debug
390           Enable debugging output
391
392       --group
393           Team to use. Use "salsa search_group name" to find it.
394
395           If you want to use a subgroup, you have to set its full path:
396
397             salsa --group perl-team/modules/packages check_repo lemonldap-ng
398
399           ".devscripts" value: SALSA_GROUP
400
401           Be careful when you use SALSA_GROUP in your ".devscripts" file.
402           Every salsa command will be executed in group space, for example if
403           you want to propose a little change in a project using salsa fork +
404           salsa mr, this "fork" will be done in group space unless you set a
405           --user/--user-id.  Prefer to use an alias in your ".bashrc" file.
406           Example:
407
408             alias jsteam_admin="salsa --group js-team"
409
410           or
411
412             alias jsteam_admin="salsa --conf-file ~/.js.conf
413
414           or to use both .devscripts and .js.conf:
415
416             alias jsteam_admin="salsa --conf-file +~/.js.conf
417
418           then you can fix SALSA_GROUP in "~/.js.conf"
419
420           To enable bash completion for your alias, add this in your .bashrc
421           file:
422
423             _completion_loader salsa
424             complete -F _salsa_completion jsteam_admin
425
426       --group-id
427           Group id to use. Use "salsa search_group name" to find it.
428
429           ".devscripts" value: SALSA_GROUP_ID
430
431           Be careful when you use SALSA_GROUP_ID in your ".devscripts" file.
432           Every salsa command will be executed in group space, for example if
433           you want to propose a little change in a project using salsa fork +
434           salsa mr, this "fork" will be done in group space unless you set a
435           --user/--user-id.  Prefer to use an alias in your ".bashrc" file.
436           Example:
437
438             alias jsteam_admin="salsa --group-id 2666"
439
440           or
441
442             alias jsteam_admin="salsa --conf-file ~/.js.conf
443
444           then you can fix SALSA_GROUP_ID in "~/.js.conf"
445
446       --help: displays this manpage
447       -i, --info
448           Prompt before sensible changes.
449
450           ".devscripts" value: SALSA_INFO (yes/no)
451
452       --path
453           Repo path. Default to group or user path.
454
455           ".devscripts" value: SALSA_REPO_PATH
456
457       --token
458           Token value (see above).
459
460       --token-file
461           File to find token (see above).
462
463       --user
464           Username to use. If neither --group, --group-id, --user or
465           --user-id is set, salsa uses current user id (corresponding to
466           salsa private token).
467
468       --user-id
469           User id to use. Use "salsa search_user name" to find one. If
470           neither --group, --group-id, --user or --user-id is set, salsa uses
471           current user id (corresponding to salsa private token).
472
473           ".devscripts" value: SALSA_USER_ID
474
475       --verbose
476           Enable verbose output.
477
478       --yes
479           Never ask for consent.
480
481           ".devscripts" value: SALSA_YES (yes/no)
482
483   List/search repo options
484       --archived --no-archived
485           Instead of looking to active projects, list or search in archived
486           projects.  Note that you can't have both archived and unarchived
487           projects in the same request. Default: no (ie --no-archived).
488
489           ".devscripts" value: SALSA_ARCHIVED (yes/no)
490
491   Update/create repo options
492       --all
493           When set, all project of group/user are affected by command.
494
495           --skip: ignore project with --all. Example:
496                 salsa update_repo --tagpending --all --skip qa --skip devscripts
497
498               ".devscripts" value: SALSA_SKIP. To set multiples values, use
499               spaces.  Example
500
501                 SALSA_SKIP=qa devscripts
502
503           --skip-file: ignore projects in this file (1 project per line)
504                 salsa update_repo --tagpending --all --skip-file ~/.skip
505
506               ".devscripts" value: SALSA_SKIP_FILE
507
508       --ci-config-path
509           Configure configuration file path of GitLab CI. Default: empty.
510           Example:
511
512             salsa update_safe --ci-config-path recipes/debian.yml@salsa-ci-team/pipeline debian/devscripts
513
514           ".devscripts" value: SALSA_CI_CONFIG_PATH
515
516       --desc --no-desc
517           Configure repo description using pattern given in desc-pattern
518
519           ".devscripts" value: SALSA_DESC (yes/no)
520
521       --desc-pattern
522           Repo description pattern. Default to "Debian package %p". "%p" is
523           replaced by repo name, while "%P" is replaced by repo name given in
524           command (may contains full path).
525
526           ".devscripts" value: SALSA_DESC_PATTERN
527
528       --email, --no-email, --disable-email
529           Enable, ignore or disable email-on-push.
530
531           ".devscripts" value: SALSA_EMAIL (yes/ignore/no, default: ignore)
532
533       --email-recipient
534           Email-on-push recipient. Can be multi valued:
535
536             $ salsa update_safe myrepo \
537                   --email-recipient foo@foobar.org \
538                   --email-recipient bar@foobar.org
539
540           If recipient value contains "%p", it is replaced by project name.
541
542           ".devscripts" value: SALSA_EMAIL_RECIPIENTS (use spaces to separate
543           multiples recipients)
544
545       --enable-issues, --no-enable-issues, --disable-issues,
546       --no-disable-issues
547           Enable, ignore or disable issues.
548
549           ".devscripts" values: SALSA_ENABLE_ISSUES (yes/ignore/no, default:
550           ignore)
551
552       --enable-mr, --no-enable-mr, --disable-mr, --no-disable-mr
553           Enable, ignore or disable merge requests.
554
555           ".devscripts" values: SALSA_ENABLE_MR (yes/ignore/no, default:
556           ignore)
557
558       --irc-channel
559           IRC channel for KGB or Irker. Can be used more than one time only
560           with --irker.
561
562           Important: channel must not include the first "#". If salsa finds a
563           channel starting with "#", it will consider that the channel starts
564           with 2 "#"!
565
566           ".devscript" value: SALSA_IRC_CHANNEL.
567
568           Multiple values must be space separated.
569
570           Since configuration files are read using sh, be careful when using
571           "#": you must enclose the channel with quotes, else sh will
572           consider it as a comment and will ignore this value.
573
574       --irker, --no-irker, --disable-irker
575           Enable, ignore or disable Irker service
576
577           ".devscripts" values: SALSA_IRKER (yes/ignore/no, default: ignore)
578
579       --irker-host
580           Irker host. Default: ruprecht.snow-crash.org
581
582           ".devscripts" value: SALSA_IRKER_HOST
583
584       --irker-port
585           Irker port. Default: empty (default value)
586
587           ".devscripts" value: SALSA_IRKER_PORT
588
589       --kgb, --no-kgb, --disable-kgb
590           Enable, ignore or disable KGB webhook.
591
592           ".devscripts" value: SALSA_KGB (yes/ignore/no, default: ignore)
593
594       --kgb-options
595           List of KGB enabled options (comma separated). Default:
596           issues_events, merge_requests_events, note_events, pipeline_events,
597           push_events, tag_push_events, wiki_page_events,
598           enable_ssl_verification
599
600             $ salsa update_safe debian/devscripts --kgb --irc-channel devscripts \
601               --kgb-options 'merge_requests_events,issues_events,enable_ssl_verification'
602
603           List of available options: confidential_comments_events,
604           confidential_issues_events, confidential_note_events,
605           enable_ssl_verification, issues_events, job_events,
606           merge_requests_events, note_events, pipeline_events,
607           tag_push_events, wiki_page_events
608
609           ".devscripts" value: SALSA_KGB_OPTIONS
610
611       --no-fail
612           Don't stop on error when using update_repo with --all.
613
614           ".devscripts" value: SALSA_NO_FAIL (yes/no)
615
616       --rename-head, --no-rename-head
617           Rename HEAD branch given by --source-branch into --dest-branch and
618           change "default branch" of project. Works only with update_repo.
619
620           ".devscripts" value: SALSA_RENAME_HEAD (yes/no)
621
622           --source-branch: default "master"
623               ".devscripts" value: SALSA_SOURCE_BRANCH
624
625           --dest-branch: default "debian/master"
626               ".devscripts" value: SALSA_DEST_BRANCH
627
628       --tagpending, --no-tagpending, --disable-tagpending
629           Enable, ignore or disable "tagpending" webhook.
630
631           ".devscripts" value: SALSA_TAGPENDING (yes/ignore/no, default:
632           ignore)
633
634   Merge requests options
635       --mr-title
636           Title for merge request. Default: last commit title.
637
638       --mr-desc
639           Description of new MR. Default:
640
641           empty if --mr-title is set
642           last commit description if any
643       --mr-dst-branch (or second command line argument)
644           Destination branch. Default to "master".
645
646       --mr-dst-project (or first command line argument)
647           Destination project. Default: project from which the current
648           project was forked; or, if not found, "upstream" value found using
649           git remote --verbose show; or using source project.
650
651           If --mr-dst-project is set to same, salsa will use source project
652           as destination.
653
654       --mr-src-branch
655           Source branch. Default: current branch.
656
657       --mr-src-project
658           Source project. Default: current project found using git remote
659           --verbose show.
660
661       --mr-allow-squash, --no-mr-allow-squash
662           Allow upstream project to squash your commits, this is the default.
663
664           ".devscripts" value: SALSA_MR_ALLOW_SQUASH (yes/no)
665
666       --mr-remove-source-branch, --no-mr-remove-source-branch
667           Remove source branch if merge request is accepted. Default: no.
668
669           ".devscripts" value: SALSA_MR_REMOVE_SOURCE_BRANCH (yes/no)
670
671   Options to manage other Gitlab instances
672       --api-url
673           GitLab API. Default: <https://salsa.debian.org/api/v4>.
674
675           ".devscripts" value: SALSA_API_URL
676
677       --git-server-url
678           Default to "git@salsa.debian.org:"
679
680           ".devscripts" value: SALSA_GIT_SERVER_URL
681
682       --irker-server-url
683           Default to "ircs://irc.oftc.net:6697/"
684
685           ".devscripts" value: SALSA_IRKER_SERVER_URL
686
687       --kgb-server-url
688           Default to <http://kgb.debian.net:9418/webhook/?channel=>
689
690           ".devscripts" value: SALSA_KGB_SERVER_URL
691
692       --tagpending-server-url
693           Default to <https://webhook.salsa.debian.org/tagpending/>
694
695           ".devscripts" value: SALSA_TAGPENDING_SERVER_URL
696
697       Configuration file example
698
699       Example to use salsa with <https://gitlab.ow2.org> (group "lemonldap-
700       ng"):
701
702         SALSA_TOKEN=`cat ~/.ow2-gitlab-token`
703         SALSA_API_URL=https://gitlab.ow2.org/api/v4
704         SALSA_GIT_SERVER_URL=git@gitlab.ow2.org:
705         SALSA_GROUP_ID=34
706
707       Then to use it, add something like this in your ".bashrc" file:
708
709         alias llng_admin='salsa --conffile ~/.salsa-ow2.conf'
710

SEE ALSO

712       dpt-salsa
713

AUTHOR

715       Xavier Guimard <yadd@debian.org>
716
718       Copyright (C) 2018, Xavier Guimard <yadd@debian.org>
719
720       It contains code formerly found in dpt-salsa (pkg-perl-tools) copyright
721       2018, gregor herrmann <gregoa@debian.org>.
722
723       This library is free software; you can redistribute it and/or modify it
724       under the terms of the GNU General Public License as published by the
725       Free Software Foundation; either version 2, or (at your option) any
726       later version.
727
728       This program is distributed in the hope that it will be useful, but
729       WITHOUT ANY WARRANTY; without even the implied warranty of
730       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
731       General Public License for more details.
732
733       You should have received a copy of the GNU General Public License along
734       with this program.  If not, see <http://www.gnu.org/licenses/>.
735
736
737
738Debian Utilities                  2022-07-21                          SALSA(1)
Impressum