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 add_user
60 Add a user to a group.
61 salsa --group js-group add_user guest foouser
63 salsa --group-id 1234 add_user guest foouser
64 salsa --group-id 1234 add_user maintainer 1245
65 First argument is the GitLab's access levels: guest, reporter,
67 developer, maintainer, owner.
68 del_user
70 Remove a user from a group
71 salsa --group js-team del_user foouser
73 salsa --group-id=1234 del_user foouser
74 list_groups
76 List sub groups of current one if group is set, groups of current
77 user else.
78 group
80 Show group members.
81 salsa --group js-team group
83 salsa --group-id 1234 group
84 search_group
86 Search for a group using given string. Shows group id and other
87 information.
88 salsa search_group perl-team
90 salsa search_group perl-team/modules
91 salsa search_group 2666
92 search_user
94 Search for a user using given string. Shows user id and other
95 information.
96 salsa search_user yadd
98 update_user
100 Update user role in a group.
101 salsa --group-id 1234 update_user guest foouser
103 salsa --group js-team update_user maintainer 1245
104 First argument is the GitLab's access levels: guest, reporter,
106 developer, maintainer, owner.
107 whoami
109 Gives information on the token owner
110 salsa whoami
112 Managing repositories
114 One of "--group", "--group-id", "--user" or "--user-id" is required to
115 manage repositories. If both are set, salsa warns and only
116 "--user"/"--user-id" is used. If none is given, salsa uses current user
117 id (token owner).
118 check_repo
120 Verify that repo(s) are well configured. It works exactly like
121 update_repo except that it does not modify anything but just lists
122 projects not well configured with found errors.
123 salsa --user yadd --tagpending --kgb --irc=devscripts check_repo test
125 salsa --group js-team check_repo --all
126 salsa --group js-team --rename-head check_repo test1 test2 test3
127 checkout or co
129 Clone repo in current dir. If directory already exists, update
130 local repo.
131 salsa --user yadd co devscripts
133 salsa --group js-team co node-mongodb
134 salsa co js-team/node-mongodb
135 create_repo
137 Create public empty project. If "--group"/"--group-id" is set,
138 project is created in group directory, else in user directory.
139 salsa --user yadd create_repo test
141 salsa --group js-team --kgb --irc-channel=devscripts create_repo test
142 del_repo
144 Delete a repository.
145 fork
147 Forks a project in group/user repository and set "upstream" to
148 original project. Example:
149 $ salsa fork js-team/node-mongodb --verbose
151 ...
152 salsa.pl info: node-mongodb ready in node-mongodb/
153 $ cd node-mongodb
154 $ git remote --verbose show
155 origin git@salsa.debian.org:me/node-mongodb (fetch)
156 origin git@salsa.debian.org:me/node-mongodb (push)
157 upstream git@salsa.debian.org:js-team/node-mongodb (fetch)
158 upstream git@salsa.debian.org:js-team/node-mongodb (push)
159 For a group:
161 salsa fork --group js-team user/node-foo
163 forks
165 List forks of project(s).
166 salsa forks qa/qa debian/devscripts
168 Project can be set using full path or using --group/--group-id or
170 --user/--user-id, else it is searched in current user namespace.
171 ls or list_repos
173 Shows projects owned by user or group. If second argument exists,
174 search only matching projects
175 salsa --group js-team list_repos
177 salsa --user yadd list_repos foo*
178 merge_request, mr
180 Creates a merge request.
181 Suppose you created a fork using salsa fork, modify some things in
183 a new branch using one commit and want to propose it to original
184 project (branch "master"). You just have to launch this in source
185 directory:
186 salsa mr
188 Other example:
190 salsa mr --mr-dst-project debian/foo --mr-dst-branch debian/master
192 or simply
194 salsa mr debian/foo debian/master
196 Note that unless destination project has been set using command
198 line, salsa merge_request will search it in the following order:
199 using GitLab API: salsa will detect from where this project was
201 forked
202 using "upstream" origin
203 else salsa will use source project as destination project
204 To force salsa to use source project as destination project, you
206 can use "same":
207 salsa mr --mr-dst-project same
209 # or
210 salsa mr same
211 New merge request will be created using last commit title and
213 description.
214 See --mr-* options for more.
216 merge_requests, mrs
218 List opened merge requests for project(s)
219 salsa mrs qa/qa debian/devscripts
221 Project can be set using full path or using --group/--group-id or
223 --user/--user-id, else it is searched in current user namespace.
224 protect_branch
226 Protect/unprotect a branch.
227 Set protection
229 # project branch merge push
230 salsa --group js-team protect_branch node-mongodb master m d
231 "merge" and "push" can be one of:
233 o, owner: owner only
235 m, maintainer: o + maintainers allowed
236 d, developer: m + developers allowed
237 r, reporter: d + reporters allowed
238 g, guest: r + guest allowed
239 Unprotect
240 salsa --group js-team protect_branch node-mongodb master no
241 protected_branches
243 List protected branches
244 salsa --group js-team protected_branches node-mongodb
246 push_repo
248 Create a new project from a local Debian source directory
249 configured with git.
250 push_repo executes the following steps:
252 gets project name using debian/changelog file;
254 launches git remote add upstream ...;
255 launches create_repo;
256 pushes local repo.
257 Examples:
259 salsa --user yadd push_repo ./test
261 salsa --group js-team --kgb --irc-channel=devscripts push_repo .
262 rename_branch
264 Rename branch given in --source-branch with name given in
265 --dest-branch. You can use --no-fail and --all options here.
266 search, search_project, search_repo
268 Search for a project using given string. Shows name, owner id and
269 other information.
270 salsa search devscripts
272 salsa search debian/devscripts
273 salsa search 18475
274 update_repo
276 Configure repo(s) using parameters given to command line. A repo
277 name has to be given unless --all is set. Prefer to use
278 update_safe.
279 salsa --user yadd --tagpending --kgb --irc=devscripts update_repo test
281 salsa --group js-team update_repo --all
282 salsa --group js-team --rename-head update_repo test1 test2 test3
283 salsa update_repo js-team/node-mongodb --kgb --irc debian-js
284 By default when using --all, salsa will fail on first error. If you
286 want to continue, set --no-fail. In this case, salsa will display a
287 warning for each project that has fail but continue with next
288 project. Then to see full errors, set --verbose.
289 update_safe
291 Launch check_repo and ask before launching update_repo (unless
292 --yes).
293 salsa --user yadd --tagpending --kgb --irc=devscripts update_safe test
295 salsa --group js-team update_safe --all
296 salsa --group js-team --rename-head update_safe test1 test2 test3
297 salsa update_safe js-team/node-mongodb --kgb --irc debian-js
298 Other
300 purge_cache
301 Empty local cache.
302
304 General options
305 -C, --chdir
306 Change directory before launching command
307 salsa -C ~/debian co debian/libapache2-mod-fcgid
309 --cache-file
311 File to store cached values. Default to ~/.cache/salsa.json. An
312 empty value disables cache.
313 ".devscripts" value: SALSA_CACHE_FILE
315 --no-cache
317 Disable cache usage. Same as --cache-file ''
318 --conffile, --conf-file
320 Add or replace default configuration files ("/etc/devscripts.conf"
321 and "~/.devscripts"). This can only be used as the first option
322 given on the command-line.
323 replace:
325 salsa --conf-file test.conf <command>...
326 salsa --conf-file test.conf --conf-file test2.conf <command>...
327 add:
329 salsa --conf-file +test.conf <command>...
330 salsa --conf-file +test.conf --conf-file +test2.conf <command>...
331 If one --conf-file has no "+", default configuration files are
333 ignored.
334 --no-conf, --noconf
336 Don't read any configuration files. This can only be used as the
337 first option given on the command-line.
338 --debug
340 Enable debugging output
341 --group
343 Team to use. Use "salsa search_group name" to find it.
344 ".devscripts" value: SALSA_GROUP
346 Be careful when you use SALSA_GROUP in your ".devscripts" file.
348 Every salsa command will be executed in group space, for example if
349 you want to propose a little change in a project using salsa fork +
350 salsa mr, this "fork" will be done in group space unless you set a
351 --user/--user-id. Prefer to use an alias in your ".bashrc" file.
352 Example:
353 alias jsteam_admin="salsa --group js-team"
355 or
357 alias jsteam_admin="salsa --conf-file ~/.js.conf
359 then you can fix SALSA_GROUP in "~/.js.conf"
361 --group-id
363 Group id to use. Use "salsa search_group name" to find it.
364 ".devscripts" value: SALSA_GROUP_ID
366 Be careful when you use SALSA_GROUP_ID in your ".devscripts" file.
368 Every salsa command will be executed in group space, for example if
369 you want to propose a little change in a project using salsa fork +
370 salsa mr, this "fork" will be done in group space unless you set a
371 --user/--user-id. Prefer to use an alias in your ".bashrc" file.
372 Example:
373 alias jsteam_admin="salsa --group-id 2666"
375 or
377 alias jsteam_admin="salsa --conf-file ~/.js.conf
379 then you can fix SALSA_GROUP_ID in "~/.js.conf"
381 --help: displays this manpage
383 -i, --info
384 Prompt before sensible changes.
385 ".devscripts" value: SALSA_INFO (yes/no)
387 --path
389 Repo path. Default to group or user path.
390 ".devscripts" value: SALSA_REPO_PATH
392 --token
394 Token value (see above).
395 --token-file
397 File to find token (see above).
398 --user
400 Username to use. If neither --group, --group-id, --user or
401 --user-id is set, salsa uses current user id (corresponding to
402 salsa private token).
403 --user-id
405 User id to use. Use "salsa search_user name" to find one. If
406 neither --group, --group-id, --user or --user-id is set, salsa uses
407 current user id (corresponding to salsa private token).
408 ".devscripts" value: SALSA_USER_ID
410 --verbose
412 Enable verbose output.
413 --yes
415 Never ask for consent.
416 ".devscripts" value: SALSA_YES (yes/no)
418 Update/create repo options
420 --all
421 When set, all project of group/user are affected by command.
422 --skip: ignore project with --all. Example:
424 salsa update_repo --tagpending --all --skip qa --skip devscripts
425 ".devscripts" value: SALSA_SKIP. To set multiples values, use
427 spaces. Example
428 SALSA_SKIP=qa devscripts
430 --skip-file: ignore projects in this file (1 project per line)
432 salsa update_repo --tagpending --all --skip-file ~/.skip
433 ".devscripts" value: SALSA_SKIP_FILE
435 --ci-config-path
437 Configure configuration file path of GitLab CI. Default: empty.
438 Example:
439 salsa update_safe --ci-config-path debian/.gitlab-ci.yml debian/devscripts
441 ".devscripts" value: SALSA_CI_CONFIG_PATH
443 --desc --no-desc
445 Configure repo description using pattern given in desc-pattern
446 ".devscripts" value: SALSA_DESC (yes/no)
448 --desc-pattern
450 Repo description pattern. Default to "Debian package %p". "%p" is
451 replaced by repo name, while "%P" is replaced by repo name given in
452 command (may contains full path).
453 ".devscripts" value: SALSA_DESC_PATTERN
455 --email, --no-email, --disable-email
457 Enable, ignore or disable email-on-push.
458 ".devscripts" value: SALSA_EMAIL (yes/ignore/no, default: ignore)
460 --email-recipient
462 Email-on-push recipient. Can be multi valued:
463 $ salsa update_safe myrepo \
465 --email-recipient foo@foobar.org \
466 --email-recipient bar@foobar.org
467 If recipient value contains "%p", it is replaced by project name.
469 ".devscripts" value: SALSA_EMAIL_RECIPIENTS (use spaces to separate
471 multiples recipients)
472 --enable-issues, --no-enable-issues, --disable-issues,
474 --no-disable-issues
475 Enable, ignore or disable issues.
476 ".devscripts" values: SALSA_ENABLE_ISSUES (yes/ignore/no, default:
478 ignore)
479 --enable-mr, --no-enable-mr, --disable-mr, --no-disable-mr
481 Enable, ignore or disable merge requests.
482 ".devscripts" values: SALSA_ENABLE_MR (yes/ignore/no, default:
484 ignore)
485 --irc-channel
487 IRC channel for KGB or Irker. Can be used more than one time only
488 with --irker.
489 Important: channel must not include the first "#". If salsa finds a
491 channel starting with "#", it will consider that the channel starts
492 with 2 "#"!
493 ".devscript" value: SALSA_IRC_CHANNEL.
495 Multiple values must be space separated.
497 Since configuration files are read using sh, be careful when using
499 "#": you must enclose the channel with quotes, else sh will
500 consider it as a comment and will ignore this value.
501 --irker, --no-irker, --disable-irker
503 Enable, ignore or disable Irker service
504 ".devscripts" values: SALSA_IRKER (yes/ignore/no, default: ignore)
506 --irker-host
508 Irker host. Default: ruprecht.snow-crash.org
509 ".devscripts" value: SALSA_IRKER_HOST
511 --irker-port
513 Irker port. Default: empty (default value)
514 ".devscripts" value: SALSA_IRKER_PORT
516 --kgb, --no-kgb, --disable-kgb
518 Enable, ignore or disable KGB webhook.
519 ".devscripts" value: SALSA_KGB (yes/ignore/no, default: ignore)
521 --no-fail
523 Don't stop on error when using update_repo with --all.
524 ".devscripts" value: SALSA_NO_FAIL (yes/no)
526 --rename-head, --no-rename-head
528 Rename HEAD branch given by --source-branch into --dest-branch and
529 change "default branch" of project. Works only with update_repo.
530 ".devscripts" value: SALSA_RENAME_HEAD (yes/no)
532 --source-branch: default "master"
534 ".devscripts" value: SALSA_SOURCE_BRANCH
535 --dest-branch: default "debian/master"
537 ".devscripts" value: SALSA_DEST_BRANCH
538 --tagpending, --no-tagpending, --disable-tagpending
540 Enable, ignore or disable "tagpending" webhook.
541 ".devscripts" value: SALSA_TAGPENDING (yes/ignore/no, default:
543 ignore)
544 Merge requests options
546 --mr-title
547 Title for merge request. Default: last commit title.
548 --mr-desc
550 Description of new MR. Default:
551 empty if --mr-title is set
553 last commit description if any
554 --mr-dst-branch (or second command line argument)
555 Destination branch. Default to "master".
556 --mr-dst-project (or first command line argument)
558 Destination project. Default: project from which the current
559 project was forked; or, if not found, "upstream" value found using
560 git remote --verbose show; or using source project.
561 If --mr-dst-project is set to same, salsa will use source project
563 as destination.
564 --mr-src-branch
566 Source branch. Default: current branch.
567 --mr-src-project
569 Source project. Default: current project found using git remote
570 --verbose show.
571 --mr-allow-squash, --no-mr-allow-squash
573 Allow upstream project to squash your commits, this is the default.
574 ".devscripts" value: SALSA_MR_ALLOW_SQUASH (yes/no)
576 --mr-remove-source-branch, --no-mr-remove-source-branch
578 Remove source branch if merge request is accepted. Default: no.
579 ".devscripts" value: SALSA_MR_REMOVE_SOURCE_BRANCH (yes/no)
581 Options to manage other Gitlab instances
583 --api-url
584 GitLab API. Default: <https://salsa.debian.org/api/v4>.
585 ".devscripts" value: SALSA_API_URL
587 --git-server-url
589 Default to "git@salsa.debian.org:"
590 ".devscripts" value: SALSA_GIT_SERVER_URL
592 --irker-server-url
594 Default to "ircs://irc.oftc.net:6697/"
595 ".devscripts" value: SALSA_IRKER_SERVER_URL
597 --kgb-server-url
599 Default to <http://kgb.debian.net:9418/webhook/?channel=>
600 ".devscripts" value: SALSA_KGB_SERVER_URL
602 --tagpending-server-url
604 Default to <https://webhook.salsa.debian.org/tagpending/>
605 ".devscripts" value: SALSA_TAGPENDING_SERVER_URL
607 Configuration file example
609 Example to use salsa with <https://gitlab.ow2.org> (group "lemonldap-
611 ng"):
612 SALSA_TOKEN=`cat ~/.ow2-gitlab-token`
614 SALSA_API_URL=https://gitlab.ow2.org/api/v4
615 SALSA_GIT_SERVER_URL=git@gitlab.ow2.org:
616 SALSA_GROUP_ID=34
617 Then to use it, add something like this in your ".bashrc" file:
619 alias llng_admin='salsa --conffile ~/.salsa-ow2.conf'
621
623 dpt-salsa
624
626 Xavier Guimard <yadd@debian.org>
627
629 Copyright (C) 2018, Xavier Guimard <yadd@debian.org>
630 It contains code formely found in dpt-salsa (pkg-perl-tools) copyright
632 2018, gregor herrmann <gregoa@debian.org>.
633 This library is free software; you can redistribute it and/or modify it
635 under the terms of the GNU General Public License as published by the
636 Free Software Foundation; either version 2, or (at your option) any
637 later version.
638 This program is distributed in the hope that it will be useful, but
640 WITHOUT ANY WARRANTY; without even the implied warranty of
641 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
642 General Public License for more details.
643 You should have received a copy of the GNU General Public License along
645 with this program. If not, see <http://www.gnu.org/licenses/>.
646Debian Utilities 2019-02-18 SALSA(1)