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
29 salsa is a designed to create and configure repositories on
30 <https://salsa.debian.org> and manage users of groups.
31 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 SALSA_TOKEN=abcdefghi
37 or
39 SALSA_TOKEN=`cat ~/.token`
41 or
43 SALSA_TOKEN_FILE=~/.dpt.conf
45 If you choose to link another file using SALSA_TOKEN_FILE, it must
47 contain a line with one of (no differences):
48 <anything>SALSA_PRIVATE_TOKEN=xxxx
50 <anything>SALSA_TOKEN=xxxx
51 This allows for example to use dpt(1) configuration file (~/.dpt.conf)
53 which contains:
54 DPT_SALSA_PRIVATE_TOKEN=abcdefghi
56
58 Managing users and groups
59 join
60 Request access to a group.
61 salsa join js-team
63 salsa join --group js-team
64 salsa join --group-id 1234
65 add_user
67 Add a user to a group.
68 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 First argument is the GitLab's access levels: guest, reporter,
74 developer, maintainer, owner.
75 del_user
77 Remove a user from a group
78 salsa --group js-team del_user foouser
80 salsa --group-id=1234 del_user foouser
81 list_groups
83 List sub groups of current one if group is set, groups of current
84 user else.
85 group
87 Show group members.
88 salsa --group js-team group
90 salsa --group-id 1234 group
91 search_group
93 Search for a group using given string. Shows group id and other
94 information.
95 salsa search_group perl-team
97 salsa search_group perl-team/modules
98 salsa search_group 2666
99 search_user
101 Search for a user using given string. Shows user id and other
102 information.
103 salsa search_user yadd
105 update_user
107 Update user role in a group.
108 salsa --group-id 1234 update_user guest foouser
110 salsa --group js-team update_user maintainer 1245
111 First argument is the GitLab's access levels: guest, reporter,
113 developer, maintainer, owner.
114 whoami
116 Gives information on the token owner
117 salsa whoami
119 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 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 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 checkout or co
136 Clone repo in current dir. If directory already exists, update
137 local repo.
138 salsa --user yadd co devscripts
140 salsa --group js-team co node-mongodb
141 salsa co js-team/node-mongodb
142 You can clone more than one repository or all repositories of a
144 group or a user:
145 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 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 salsa --user yadd create_repo test
156 salsa --group js-team --kgb --irc-channel=devscripts create_repo test
157 del_repo
159 Delete a repository.
160 fork
162 Forks a project in group/user repository and set "upstream" to
163 original project. Example:
164 $ 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 For a group:
176 salsa fork --group js-team user/node-foo
178 forks
180 List forks of project(s).
181 salsa forks qa/qa debian/devscripts
183 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 push
188 Push relevant packaging refs to origin Git remote. To be run from
189 packaging working directory.
190 salsa push
192 It pushes the following refs to the configured remote for the
194 debian-branch or, falling back, to the "origin" remote:
195 "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 salsa --group js-team list_repos
210 salsa --user yadd list_repos foo*
211 merge_request, mr
213 Creates a merge request.
214 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 salsa mr
221 Other example:
223 salsa mr --mr-dst-project debian/foo --mr-dst-branch debian/master
225 or simply
227 salsa mr debian/foo debian/master
229 Note that unless destination project has been set using command
231 line, salsa merge_request will search it in the following order:
232 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 To force salsa to use source project as destination project, you
239 can use "same":
240 salsa mr --mr-dst-project same
242 # or
243 salsa mr same
244 New merge request will be created using last commit title and
246 description.
247 See --mr-* options for more.
249 merge_requests, mrs
251 List opened merge requests for project(s)
252 salsa mrs qa/qa debian/devscripts
254 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 protect_branch
259 Protect/unprotect a branch.
260 Set protection
262 # project branch merge push
263 salsa --group js-team protect_branch node-mongodb master m d
264 "merge" and "push" can be one of:
266 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 protected_branches
276 List protected branches
277 salsa --group js-team protected_branches node-mongodb
279 push_repo
281 Create a new project from a local Debian source directory
282 configured with git.
283 push_repo executes the following steps:
285 gets project name using debian/changelog file;
287 launches git remote add upstream ...;
288 launches create_repo;
289 pushes local repo.
290 Examples:
292 salsa --user yadd push_repo ./test
294 salsa --group js-team --kgb --irc-channel=devscripts push_repo .
295 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 search, search_project, search_repo
301 Search for a project using given string. Shows name, owner id and
302 other information.
303 salsa search devscripts
305 salsa search debian/devscripts
306 salsa search 18475
307 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 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 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 update_safe
324 Launch check_repo and ask before launching update_repo (unless
325 --yes).
326 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 Other
333 purge_cache
334 Empty local cache.
335
337 General options
338 -C, --chdir
339 Change directory before launching command
340 salsa -C ~/debian co debian/libapache2-mod-fcgid
342 --cache-file
344 File to store cached values. Default to ~/.cache/salsa.json. An
345 empty value disables cache.
346 ".devscripts" value: SALSA_CACHE_FILE
348 --no-cache
350 Disable cache usage. Same as --cache-file ''
351 --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 replace:
358 salsa --conf-file test.conf <command>...
359 salsa --conf-file test.conf --conf-file test2.conf <command>...
360 add:
362 salsa --conf-file +test.conf <command>...
363 salsa --conf-file +test.conf --conf-file +test2.conf <command>...
364 If one --conf-file has no "+", default configuration files are
366 ignored.
367 --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 --debug
373 Enable debugging output
374 --group
376 Team to use. Use "salsa search_group name" to find it.
377 If you want to use a subgroup, you have to set its full path:
379 salsa --group perl-team/modules/packages check_repo lemonldap-ng
381 ".devscripts" value: SALSA_GROUP
383 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 alias jsteam_admin="salsa --group js-team"
392 or
394 alias jsteam_admin="salsa --conf-file ~/.js.conf
396 or to use both .devscripts and .js.conf:
398 alias jsteam_admin="salsa --conf-file +~/.js.conf
400 then you can fix SALSA_GROUP in "~/.js.conf"
402 To enable bash completion for your alias, add this in your .bashrc
404 file:
405 _completion_loader salsa
407 complete -F _salsa_completion jsteam_admin
408 --group-id
410 Group id to use. Use "salsa search_group name" to find it.
411 ".devscripts" value: SALSA_GROUP_ID
413 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 alias jsteam_admin="salsa --group-id 2666"
422 or
424 alias jsteam_admin="salsa --conf-file ~/.js.conf
426 then you can fix SALSA_GROUP_ID in "~/.js.conf"
428 --help: displays this manpage
430 -i, --info
431 Prompt before sensible changes.
432 ".devscripts" value: SALSA_INFO (yes/no)
434 --path
436 Repo path. Default to group or user path.
437 ".devscripts" value: SALSA_REPO_PATH
439 --token
441 Token value (see above).
442 --token-file
444 File to find token (see above).
445 --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 --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 ".devscripts" value: SALSA_USER_ID
457 --verbose
459 Enable verbose output.
460 --yes
462 Never ask for consent.
463 ".devscripts" value: SALSA_YES (yes/no)
465 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 ".devscripts" value: SALSA_ARCHIVED (yes/no)
473 Update/create repo options
475 --all
476 When set, all project of group/user are affected by command.
477 --skip: ignore project with --all. Example:
479 salsa update_repo --tagpending --all --skip qa --skip devscripts
480 ".devscripts" value: SALSA_SKIP. To set multiples values, use
482 spaces. Example
483 SALSA_SKIP=qa devscripts
485 --skip-file: ignore projects in this file (1 project per line)
487 salsa update_repo --tagpending --all --skip-file ~/.skip
488 ".devscripts" value: SALSA_SKIP_FILE
490 --ci-config-path
492 Configure configuration file path of GitLab CI. Default: empty.
493 Example:
494 salsa update_safe --ci-config-path debian/.gitlab-ci.yml debian/devscripts
496 ".devscripts" value: SALSA_CI_CONFIG_PATH
498 --desc --no-desc
500 Configure repo description using pattern given in desc-pattern
501 ".devscripts" value: SALSA_DESC (yes/no)
503 --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 ".devscripts" value: SALSA_DESC_PATTERN
510 --email, --no-email, --disable-email
512 Enable, ignore or disable email-on-push.
513 ".devscripts" value: SALSA_EMAIL (yes/ignore/no, default: ignore)
515 --email-recipient
517 Email-on-push recipient. Can be multi valued:
518 $ salsa update_safe myrepo \
520 --email-recipient foo@foobar.org \
521 --email-recipient bar@foobar.org
522 If recipient value contains "%p", it is replaced by project name.
524 ".devscripts" value: SALSA_EMAIL_RECIPIENTS (use spaces to separate
526 multiples recipients)
527 --enable-issues, --no-enable-issues, --disable-issues,
529 --no-disable-issues
530 Enable, ignore or disable issues.
531 ".devscripts" values: SALSA_ENABLE_ISSUES (yes/ignore/no, default:
533 ignore)
534 --enable-mr, --no-enable-mr, --disable-mr, --no-disable-mr
536 Enable, ignore or disable merge requests.
537 ".devscripts" values: SALSA_ENABLE_MR (yes/ignore/no, default:
539 ignore)
540 --irc-channel
542 IRC channel for KGB or Irker. Can be used more than one time only
543 with --irker.
544 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 ".devscript" value: SALSA_IRC_CHANNEL.
550 Multiple values must be space separated.
552 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 --irker, --no-irker, --disable-irker
558 Enable, ignore or disable Irker service
559 ".devscripts" values: SALSA_IRKER (yes/ignore/no, default: ignore)
561 --irker-host
563 Irker host. Default: ruprecht.snow-crash.org
564 ".devscripts" value: SALSA_IRKER_HOST
566 --irker-port
568 Irker port. Default: empty (default value)
569 ".devscripts" value: SALSA_IRKER_PORT
571 --kgb, --no-kgb, --disable-kgb
573 Enable, ignore or disable KGB webhook.
574 ".devscripts" value: SALSA_KGB (yes/ignore/no, default: ignore)
576 --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 $ salsa update_safe debian/devscripts --kgb --irc-channel devscripts \
584 --kgb-options 'merge_requests_events,issues_events,enable_ssl_verification'
585 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 ".devscripts" value: SALSA_KGB_OPTIONS
593 --no-fail
595 Don't stop on error when using update_repo with --all.
596 ".devscripts" value: SALSA_NO_FAIL (yes/no)
598 --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 ".devscripts" value: SALSA_RENAME_HEAD (yes/no)
604 --source-branch: default "master"
606 ".devscripts" value: SALSA_SOURCE_BRANCH
607 --dest-branch: default "debian/master"
609 ".devscripts" value: SALSA_DEST_BRANCH
610 --tagpending, --no-tagpending, --disable-tagpending
612 Enable, ignore or disable "tagpending" webhook.
613 ".devscripts" value: SALSA_TAGPENDING (yes/ignore/no, default:
615 ignore)
616 Merge requests options
618 --mr-title
619 Title for merge request. Default: last commit title.
620 --mr-desc
622 Description of new MR. Default:
623 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 --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 If --mr-dst-project is set to same, salsa will use source project
635 as destination.
636 --mr-src-branch
638 Source branch. Default: current branch.
639 --mr-src-project
641 Source project. Default: current project found using git remote
642 --verbose show.
643 --mr-allow-squash, --no-mr-allow-squash
645 Allow upstream project to squash your commits, this is the default.
646 ".devscripts" value: SALSA_MR_ALLOW_SQUASH (yes/no)
648 --mr-remove-source-branch, --no-mr-remove-source-branch
650 Remove source branch if merge request is accepted. Default: no.
651 ".devscripts" value: SALSA_MR_REMOVE_SOURCE_BRANCH (yes/no)
653 Options to manage other Gitlab instances
655 --api-url
656 GitLab API. Default: <https://salsa.debian.org/api/v4>.
657 ".devscripts" value: SALSA_API_URL
659 --git-server-url
661 Default to "git@salsa.debian.org:"
662 ".devscripts" value: SALSA_GIT_SERVER_URL
664 --irker-server-url
666 Default to "ircs://irc.oftc.net:6697/"
667 ".devscripts" value: SALSA_IRKER_SERVER_URL
669 --kgb-server-url
671 Default to <http://kgb.debian.net:9418/webhook/?channel=>
672 ".devscripts" value: SALSA_KGB_SERVER_URL
674 --tagpending-server-url
676 Default to <https://webhook.salsa.debian.org/tagpending/>
677 ".devscripts" value: SALSA_TAGPENDING_SERVER_URL
679 Configuration file example
681 Example to use salsa with <https://gitlab.ow2.org> (group "lemonldap-
683 ng"):
684 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 Then to use it, add something like this in your ".bashrc" file:
691 alias llng_admin='salsa --conffile ~/.salsa-ow2.conf'
693
695 dpt-salsa
696
698 Xavier Guimard <yadd@debian.org>
699
701 Copyright (C) 2018, Xavier Guimard <yadd@debian.org>
702 It contains code formerly found in dpt-salsa (pkg-perl-tools) copyright
704 2018, gregor herrmann <gregoa@debian.org>.
705 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 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 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/>.
718Debian Utilities 2021-05-03 SALSA(1)