1SALSA(1) SALSA(1)
2
6 salsa - tool to manipulate salsa repositories and group members
7
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
30 salsa is a designed to create and configure repositories on
31 <https://salsa.debian.org> and manage users of groups.
32 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 SALSA_TOKEN=abcdefghi
38 or
40 SALSA_TOKEN=`cat ~/.token`
42 or
44 SALSA_TOKEN_FILE=~/.dpt.conf
46 If you choose to link another file using SALSA_TOKEN_FILE, it must
48 contain a line with one of (no differences):
49 <anything>SALSA_PRIVATE_TOKEN=xxxx
51 <anything>SALSA_TOKEN=xxxx
52 This allows for example to use dpt(1) configuration file (~/.dpt.conf)
54 which contains:
55 DPT_SALSA_PRIVATE_TOKEN=abcdefghi
57
59 Managing users and groups
60 join
61 Request access to a group.
62 salsa join js-team
64 salsa join --group js-team
65 salsa join --group-id 1234
66 add_user
68 Add a user to a group.
69 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 First argument is the GitLab's access levels: guest, reporter,
75 developer, maintainer, owner.
76 del_user
78 Remove a user from a group
79 salsa --group js-team del_user foouser
81 salsa --group-id=1234 del_user foouser
82 list_groups
84 List sub groups of current one if group is set, groups of current
85 user else.
86 group
88 Show group members.
89 salsa --group js-team group
91 salsa --group-id 1234 group
92 search_group
94 Search for a group using given string. Shows group id and other
95 information.
96 salsa search_group perl-team
98 salsa search_group perl-team/modules
99 salsa search_group 2666
100 search_user
102 Search for a user using given string. Shows user id and other
103 information.
104 salsa search_user yadd
106 update_user
108 Update user role in a group.
109 salsa --group-id 1234 update_user guest foouser
111 salsa --group js-team update_user maintainer 1245
112 First argument is the GitLab's access levels: guest, reporter,
114 developer, maintainer, owner.
115 whoami
117 Gives information on the token owner
118 salsa whoami
120 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 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 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 checkout or co
137 Clone repo in current dir. If directory already exists, update
138 local repo.
139 salsa --user yadd co devscripts
141 salsa --group js-team co node-mongodb
142 salsa co js-team/node-mongodb
143 You can clone more than one repository or all repositories of a
145 group or a user:
146 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 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 salsa --user yadd create_repo test
157 salsa --group js-team --kgb --irc-channel=devscripts create_repo test
158 del_repo
160 Delete a repository.
161 fork
163 Forks a project in group/user repository and set "upstream" to
164 original project. Example:
165 $ 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 For a group:
177 salsa fork --group js-team user/node-foo
179 forks
181 List forks of project(s).
182 salsa forks qa/qa debian/devscripts
184 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 push
189 Push relevant packaging refs to origin Git remote. To be run from
190 packaging working directory.
191 salsa push
193 It pushes the following refs to the configured remote for the
195 debian-branch or, falling back, to the "origin" remote:
196 "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 salsa --group js-team list_repos
211 salsa --user yadd list_repos foo*
212 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 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 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 salsa --group js-team last_ci_status --all --no-fail >/dev/null
228 merge_request, mr
230 Creates a merge request.
231 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 salsa mr
238 Other example:
240 salsa mr --mr-dst-project debian/foo --mr-dst-branch debian/master
242 or simply
244 salsa mr debian/foo debian/master
246 Note that unless destination project has been set using command
248 line, salsa merge_request will search it in the following order:
249 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 To force salsa to use source project as destination project, you
256 can use "same":
257 salsa mr --mr-dst-project same
259 # or
260 salsa mr same
261 New merge request will be created using last commit title and
263 description.
264 See --mr-* options for more.
266 merge_requests, mrs
268 List opened merge requests for project(s)
269 salsa mrs qa/qa debian/devscripts
271 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 protect_branch
276 Protect/unprotect a branch.
277 Set protection
279 # project branch merge push
280 salsa --group js-team protect_branch node-mongodb master m d
281 "merge" and "push" can be one of:
283 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 protected_branches
293 List protected branches
294 salsa --group js-team protected_branches node-mongodb
296 push_repo
298 Create a new project from a local Debian source directory
299 configured with git.
300 push_repo executes the following steps:
302 gets project name using debian/changelog file;
304 launches git remote add upstream ...;
305 launches create_repo;
306 pushes local repo.
307 Examples:
309 salsa --user yadd push_repo ./test
311 salsa --group js-team --kgb --irc-channel=devscripts push_repo .
312 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 search, search_project, search_repo
318 Search for a project using given string. Shows name, owner id and
319 other information.
320 salsa search devscripts
322 salsa search debian/devscripts
323 salsa search 18475
324 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 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 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 update_safe
341 Launch check_repo and ask before launching update_repo (unless
342 --yes).
343 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 Other
350 purge_cache
351 Empty local cache.
352
354 General options
355 -C, --chdir
356 Change directory before launching command
357 salsa -C ~/debian co debian/libapache2-mod-fcgid
359 --cache-file
361 File to store cached values. Default to ~/.cache/salsa.json. An
362 empty value disables cache.
363 ".devscripts" value: SALSA_CACHE_FILE
365 --no-cache
367 Disable cache usage. Same as --cache-file ''
368 --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 replace:
375 salsa --conf-file test.conf <command>...
376 salsa --conf-file test.conf --conf-file test2.conf <command>...
377 add:
379 salsa --conf-file +test.conf <command>...
380 salsa --conf-file +test.conf --conf-file +test2.conf <command>...
381 If one --conf-file has no "+", default configuration files are
383 ignored.
384 --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 --debug
390 Enable debugging output
391 --group
393 Team to use. Use "salsa search_group name" to find it.
394 If you want to use a subgroup, you have to set its full path:
396 salsa --group perl-team/modules/packages check_repo lemonldap-ng
398 ".devscripts" value: SALSA_GROUP
400 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 alias jsteam_admin="salsa --group js-team"
409 or
411 alias jsteam_admin="salsa --conf-file ~/.js.conf
413 or to use both .devscripts and .js.conf:
415 alias jsteam_admin="salsa --conf-file +~/.js.conf
417 then you can fix SALSA_GROUP in "~/.js.conf"
419 To enable bash completion for your alias, add this in your .bashrc
421 file:
422 _completion_loader salsa
424 complete -F _salsa_completion jsteam_admin
425 --group-id
427 Group id to use. Use "salsa search_group name" to find it.
428 ".devscripts" value: SALSA_GROUP_ID
430 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 alias jsteam_admin="salsa --group-id 2666"
439 or
441 alias jsteam_admin="salsa --conf-file ~/.js.conf
443 then you can fix SALSA_GROUP_ID in "~/.js.conf"
445 --help: displays this manpage
447 -i, --info
448 Prompt before sensible changes.
449 ".devscripts" value: SALSA_INFO (yes/no)
451 --path
453 Repo path. Default to group or user path.
454 ".devscripts" value: SALSA_REPO_PATH
456 --token
458 Token value (see above).
459 --token-file
461 File to find token (see above).
462 --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 --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 ".devscripts" value: SALSA_USER_ID
474 --verbose
476 Enable verbose output.
477 --yes
479 Never ask for consent.
480 ".devscripts" value: SALSA_YES (yes/no)
482 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 ".devscripts" value: SALSA_ARCHIVED (yes/no)
490 Update/create repo options
492 --all
493 When set, all project of group/user are affected by command.
494 --skip: ignore project with --all. Example:
496 salsa update_repo --tagpending --all --skip qa --skip devscripts
497 ".devscripts" value: SALSA_SKIP. To set multiples values, use
499 spaces. Example
500 SALSA_SKIP=qa devscripts
502 --skip-file: ignore projects in this file (1 project per line)
504 salsa update_repo --tagpending --all --skip-file ~/.skip
505 ".devscripts" value: SALSA_SKIP_FILE
507 --ci-config-path
509 Configure configuration file path of GitLab CI. Default: empty.
510 Example:
511 salsa update_safe --ci-config-path debian/.gitlab-ci.yml debian/devscripts
513 ".devscripts" value: SALSA_CI_CONFIG_PATH
515 --desc --no-desc
517 Configure repo description using pattern given in desc-pattern
518 ".devscripts" value: SALSA_DESC (yes/no)
520 --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 ".devscripts" value: SALSA_DESC_PATTERN
527 --email, --no-email, --disable-email
529 Enable, ignore or disable email-on-push.
530 ".devscripts" value: SALSA_EMAIL (yes/ignore/no, default: ignore)
532 --email-recipient
534 Email-on-push recipient. Can be multi valued:
535 $ salsa update_safe myrepo \
537 --email-recipient foo@foobar.org \
538 --email-recipient bar@foobar.org
539 If recipient value contains "%p", it is replaced by project name.
541 ".devscripts" value: SALSA_EMAIL_RECIPIENTS (use spaces to separate
543 multiples recipients)
544 --enable-issues, --no-enable-issues, --disable-issues,
546 --no-disable-issues
547 Enable, ignore or disable issues.
548 ".devscripts" values: SALSA_ENABLE_ISSUES (yes/ignore/no, default:
550 ignore)
551 --enable-mr, --no-enable-mr, --disable-mr, --no-disable-mr
553 Enable, ignore or disable merge requests.
554 ".devscripts" values: SALSA_ENABLE_MR (yes/ignore/no, default:
556 ignore)
557 --irc-channel
559 IRC channel for KGB or Irker. Can be used more than one time only
560 with --irker.
561 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 ".devscript" value: SALSA_IRC_CHANNEL.
567 Multiple values must be space separated.
569 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 --irker, --no-irker, --disable-irker
575 Enable, ignore or disable Irker service
576 ".devscripts" values: SALSA_IRKER (yes/ignore/no, default: ignore)
578 --irker-host
580 Irker host. Default: ruprecht.snow-crash.org
581 ".devscripts" value: SALSA_IRKER_HOST
583 --irker-port
585 Irker port. Default: empty (default value)
586 ".devscripts" value: SALSA_IRKER_PORT
588 --kgb, --no-kgb, --disable-kgb
590 Enable, ignore or disable KGB webhook.
591 ".devscripts" value: SALSA_KGB (yes/ignore/no, default: ignore)
593 --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 $ salsa update_safe debian/devscripts --kgb --irc-channel devscripts \
601 --kgb-options 'merge_requests_events,issues_events,enable_ssl_verification'
602 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 ".devscripts" value: SALSA_KGB_OPTIONS
610 --no-fail
612 Don't stop on error when using update_repo with --all.
613 ".devscripts" value: SALSA_NO_FAIL (yes/no)
615 --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 ".devscripts" value: SALSA_RENAME_HEAD (yes/no)
621 --source-branch: default "master"
623 ".devscripts" value: SALSA_SOURCE_BRANCH
624 --dest-branch: default "debian/master"
626 ".devscripts" value: SALSA_DEST_BRANCH
627 --tagpending, --no-tagpending, --disable-tagpending
629 Enable, ignore or disable "tagpending" webhook.
630 ".devscripts" value: SALSA_TAGPENDING (yes/ignore/no, default:
632 ignore)
633 Merge requests options
635 --mr-title
636 Title for merge request. Default: last commit title.
637 --mr-desc
639 Description of new MR. Default:
640 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 --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 If --mr-dst-project is set to same, salsa will use source project
652 as destination.
653 --mr-src-branch
655 Source branch. Default: current branch.
656 --mr-src-project
658 Source project. Default: current project found using git remote
659 --verbose show.
660 --mr-allow-squash, --no-mr-allow-squash
662 Allow upstream project to squash your commits, this is the default.
663 ".devscripts" value: SALSA_MR_ALLOW_SQUASH (yes/no)
665 --mr-remove-source-branch, --no-mr-remove-source-branch
667 Remove source branch if merge request is accepted. Default: no.
668 ".devscripts" value: SALSA_MR_REMOVE_SOURCE_BRANCH (yes/no)
670 Options to manage other Gitlab instances
672 --api-url
673 GitLab API. Default: <https://salsa.debian.org/api/v4>.
674 ".devscripts" value: SALSA_API_URL
676 --git-server-url
678 Default to "git@salsa.debian.org:"
679 ".devscripts" value: SALSA_GIT_SERVER_URL
681 --irker-server-url
683 Default to "ircs://irc.oftc.net:6697/"
684 ".devscripts" value: SALSA_IRKER_SERVER_URL
686 --kgb-server-url
688 Default to <http://kgb.debian.net:9418/webhook/?channel=>
689 ".devscripts" value: SALSA_KGB_SERVER_URL
691 --tagpending-server-url
693 Default to <https://webhook.salsa.debian.org/tagpending/>
694 ".devscripts" value: SALSA_TAGPENDING_SERVER_URL
696 Configuration file example
698 Example to use salsa with <https://gitlab.ow2.org> (group "lemonldap-
700 ng"):
701 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 Then to use it, add something like this in your ".bashrc" file:
708 alias llng_admin='salsa --conffile ~/.salsa-ow2.conf'
710
712 dpt-salsa
713
715 Xavier Guimard <yadd@debian.org>
716
718 Copyright (C) 2018, Xavier Guimard <yadd@debian.org>
719 It contains code formerly found in dpt-salsa (pkg-perl-tools) copyright
721 2018, gregor herrmann <gregoa@debian.org>.
722 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 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 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/>.
735Debian Utilities 2021-08-19 SALSA(1)