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

DESCRIPTION

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

COMMANDS

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

OPTIONS

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

SEE ALSO

695       dpt-salsa
696

AUTHOR

698       Xavier Guimard <yadd@debian.org>
699
701       Copyright (C) 2018, Xavier Guimard <yadd@debian.org>
702
703       It contains code formerly found in dpt-salsa (pkg-perl-tools) copyright
704       2018, gregor herrmann <gregoa@debian.org>.
705
706       This library is free software; you can redistribute it and/or modify it
707       under the terms of the GNU General Public License as published by the
708       Free Software Foundation; either version 2, or (at your option) any
709       later version.
710
711       This program is distributed in the hope that it will be useful, but
712       WITHOUT ANY WARRANTY; without even the implied warranty of
713       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
714       General Public License for more details.
715
716       You should have received a copy of the GNU General Public License along
717       with this program.  If not, see <http://www.gnu.org/licenses/>.
718
719
720
721Debian Utilities                  2021-05-03                          SALSA(1)
Impressum