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, it must contain a line with
47 something like:
48 <anything>SALSA_PRIVATE_TOKEN=xxxx
50 <anything>SALSA_TOKEN=xxxx
51
53 Managing users and groups
54 add_user
55 Add a user to a group.
56 salsa --group js-group add_user guest foouser
58 salsa --group-id 1234 add_user guest foouser
59 salsa --group-id 1234 add_user maintainer 1245
60 First argument is the GitLab's access levels: guest, reporter,
62 developer, maintainer, owner.
63 del_user
65 Remove a user from a group
66 salsa --group js-team del_user foouser
68 salsa --group-id=1234 del_user foouser
69 list_groups
71 List sub groups of current one if group is set, groups of current
72 user else.
73 group
75 Show group members.
76 salsa --group js-team group
78 salsa --group-id 1234 group
79 search_group
81 Search for a group using given string. Shows group id and other
82 information.
83 salsa search_group perl-team
85 salsa search_group perl-team/modules
86 salsa search_group 2666
87 search_user
89 Search for a user using given string. Shows user id and other
90 information.
91 salsa search_user yadd
93 update_user
95 Update user role in a group.
96 salsa --group-id 1234 update_user guest foouser
98 salsa --group js-team update_user maintainer 1245
99 First argument is the GitLab's access levels: guest, reporter,
101 developer, maintainer, owner.
102 whoami
104 Gives information on the token owner
105 salsa whoami
107 Managing repositories
109 One of "--group", "--group-id", "--user" or "--user-id" is required to
110 manage repositories. If both are set, salsa warns and only
111 "--user"/"--user-id" is used. If none is given, salsa uses current user
112 id (token owner).
113 check_repo
115 Verify that repo(s) are well configured. It works exactly like
116 update_repo except that it does not modify anything but just lists
117 projects not well configured with found errors.
118 salsa --user yadd --tagpending --kgb --irc=devscripts check_repo test
120 salsa --group js-team check_repo --all
121 salsa --group js-team --rename-head check_repo test1 test2 test3
122 checkout or co
124 Clone repo in current dir. If directory already exists, update
125 local repo.
126 salsa --user yadd co devscripts
128 salsa --group js-team co node-mongodb
129 salsa co js-team/node-mongodb
130 create_repo
132 Create public empty project. If "--group"/"--group-id" is set,
133 project is created in group directory, else in user directory.
134 salsa --user yadd create_repo test
136 salsa --group js-team --kgb --irc-channel=devscripts create_repo test
137 del_repo
139 Delete a repository.
140 fork
142 Forks a project in group/user repository and set "upstream" to
143 original project. Example:
144 $ salsa fork js-team/node-mongodb --verbose
146 ...
147 salsa.pl info: node-mongodb ready in node-mongodb/
148 $ cd node-mongodb
149 $ git remote --verbose show
150 origin git@salsa.debian.org:me/node-mongodb (fetch)
151 origin git@salsa.debian.org:me/node-mongodb (push)
152 upstream git@salsa.debian.org:js-team/node-mongodb (fetch)
153 upstream git@salsa.debian.org:js-team/node-mongodb (push)
154 For a group:
156 salsa fork --group js-team user/node-foo
158 forks
160 List forks of project(s).
161 salsa forks qa/qa debian/devscripts
163 Project can be set using full path or using --group/--group-id or
165 --user/--user-id, else it is searched in current user namespace.
166 ls or list_repos
168 Shows project owned by user or group. If Second argument exists,
169 search only matching projects
170 salsa --group js-team list_repos
172 salsa --user yadd list_repos foo*
173 merge_request, mr
175 Creates a merge request.
176 Suppose you created a fork using salsa fork, modify some things in
178 a new branch using one commit and want to propose it to original
179 project (branch "master"). You just have to launch this in source
180 directory:
181 salsa mr
183 Other example:
185 salsa mr --mr-dst-project debian/foo --mr-dst-branch debian/master
187 or simply
189 salsa mr debian/foo debian/master
191 Note that unless destination project has been set using command
193 line, salsa merge_request will search it in the following order:
194 using GitLab API: salsa will detect from where this project was
196 forked
197 using "upstream" origin
198 else salsa will use source project as destination project
199 To force salsa to use source project as destination project, you
201 can use "same":
202 salsa mr --mr-dst-project same
204 # or
205 salsa mr same
206 New merge request will be created using last commit title and
208 description.
209 See --mr-* options for more.
211 merge_requests, mrs
213 List opened merge requests for project(s)
214 salsa mrs qa/qa debian/devscripts
216 Project can be set using full path or using --group/--group-id or
218 --user/--user-id, else it is searched in current user namespace.
219 protect_branch
221 Protect/unprotect a branch.
222 Set protection
224 # project branch merge push
225 salsa --group js-team protect_branch node-mongodb master m d
226 "merge" and "push" can be one of:
228 o, owner: owner only
230 m, maintainer: o + maintainers allowed
231 d, developer: m + developers allowed
232 r, reporter: d + reporters allowed
233 g, guest: r + guest allowed
234 Unprotect
235 salsa --group js-team protect_branch node-mongodb master no
236 protected_branches
238 List protected branches
239 salsa --group js-team protected_branches node-mongodb
241 push_repo
243 Create a new project from a local Debian source directory
244 configured with git.
245 push_repo executes the following steps:
247 gets project name using debian/changelog file;
249 launches git remote add upstream ...;
250 launches create_repo;
251 pushes local repo.
252 Examples:
254 salsa --user yadd push_repo ./test
256 salsa --group js-team --kgb --irc-channel=devscripts push_repo .
257 rename_branch
259 Rename branch given in --source-branch with name given in
260 --dest-branch. You can use --no-fail and --all options here.
261 search, search_project, search_repo
263 Search for a project using given string. Shows name, owner id and
264 other information.
265 salsa search devscripts
267 salsa search debian/devscripts
268 salsa search 18475
269 update_repo
271 Configure repo(s) using parameters given to command line. A repo
272 name has to be given unless --all is set. Prefer to use
273 update_safe.
274 salsa --user yadd --tagpending --kgb --irc=devscripts update_repo test
276 salsa --group js-team update_repo --all
277 salsa --group js-team --rename-head update_repo test1 test2 test3
278 salsa update_repo js-team/node-mongodb --kgb --irc debian-js
279 By default when using --all, salsa will fail on first error. If you
281 want to continue, set --no-fail. In this case, salsa will display a
282 warning for each project that has fail but continue with next
283 project. Then to see full errors, set --verbose.
284 update_safe
286 Launch check_repo an ask before launching update_repo (unless
287 --yes).
288 salsa --user yadd --tagpending --kgb --irc=devscripts update_safe test
290 salsa --group js-team update_safe --all
291 salsa --group js-team --rename-head update_safe test1 test2 test3
292 salsa update_safe js-team/node-mongodb --kgb --irc debian-js
293 Other
295 purge_cache
296 Empty local cache.
297
299 General options
300 -C, --chdir
301 Change directory before launching command
302 salsa -C ~/debian co debian/libapache2-mod-fcgid
304 --cache-file
306 File to store cached values. Default to ~/.cache/salsa.json. An
307 empty value disables cache.
308 ".devscripts" value: SALSA_CACHE_FILE
310 --no-cache
312 Disable cache usage. Same as --cache-file ''
313 --conffile, --conf-file
315 Add or replace default configuration files ("/etc/devscripts.conf"
316 and "~/.devscripts"). This can only be used as the first option
317 given on the command-line.
318 replace:
320 salsa --conf-file test.conf <command>...
321 salsa --conf-file test.conf --conf-file test2.conf <command>...
322 add:
324 salsa --conf-file +test.conf <command>...
325 salsa --conf-file +test.conf --conf-file +test2.conf <command>...
326 If one --conf-file has no "+", default configuration files are
328 ignored.
329 --no-conf, --noconf
331 Don't read any configuration files. This can only be used as the
332 first option given on the command-line.
333 --debug
335 Enable debugging output
336 --group
338 Team to use. Use "salsa search_group name" to find it.
339 ".devscripts" value: SALSA_GROUP
341 Be careful when you use SALSA_GROUP in your ".devscripts" file.
343 Every salsa commands will be executed in group space, for example
344 if you want to propose a little change in a project using salsa
345 fork + salsa mr, this "fork" will be done in group space unless you
346 set a --user/--user-id. Prefer to use an alias in your ".bashrc"
347 file. Example:
348 alias jsteam_admin="salsa --group js-team"
350 or
352 alias jsteam_admin="salsa --conf-file ~/.js.conf
354 then you can fix SALSA_GROUP in "~/.js.conf"
356 --group-id
358 Group id to use. Use "salsa search_group name" to find it.
359 ".devscripts" value: SALSA_GROUP_ID
361 Be careful when you use SALSA_GROUP_ID in your ".devscripts" file.
363 Every salsa commands will be executed in group space, for example
364 if you want to propose a little change in a project using salsa
365 fork + salsa mr, this "fork" will be done in group space unless you
366 set a --user/--user-id. Prefer to use an alias in your ".bashrc"
367 file. Example:
368 alias jsteam_admin="salsa --group-id 2666"
370 or
372 alias jsteam_admin="salsa --conf-file ~/.js.conf
374 then you can fix SALSA_GROUP_ID in "~/.js.conf"
376 --help: displays this manpage
378 -i, --info
379 Prompt before sensible changes.
380 ".devscripts" value: SALSA_INFO (yes/no)
382 --path
384 Repo path. Default to group or user path.
385 ".devscripts" value: SALSA_REPO_PATH
387 --token
389 Token value (see above).
390 --token-file
392 File to find token (see above).
393 --user
395 Username to use. If neither --group, --group-id, --user or
396 --user-id is set, salsa uses current user id (corresponding to
397 salsa private token).
398 --user-id
400 User id to use. Use "salsa search_user name" to find one. If
401 neither --group, --group-id, --user or --user-id is set, salsa uses
402 current user id (corresponding to salsa private token).
403 ".devscripts" value: SALSA_USER_ID
405 --verbose
407 Enable verbose output.
408 --yes
410 Never ask for consent.
411 ".devscripts" value: SALSA_YES (yes/no)
413 Update/create repo options
415 --all
416 When set, all project of group/user are affected by command.
417 --skip: ignore project with --all. Example:
419 salsa update_repo --tagpending --all --skip qa --skip devscripts
420 ".devscripts" value: SALSA_SKIP. To set multiples values, use
422 spaces. Example
423 SALSA_SKIP=qa devscripts
425 --skip-file: ignore projects in this file (1 project per line)
427 salsa update_repo --tagpending --all --skip-file ~/.skip
428 ".devscripts" value: SALSA_SKIP_FILE
430 --ci-config-path
432 Configure configuration file path of GitLab CI. Default: empty.
433 Example:
434 salsa update_safe --ci-config-path debian/.gitlab-ci.yml debian/devscripts
436 ".devscripts" value: SALSA_CI_CONFIG_PATH
438 --desc --no-desc
440 Configure repo description using pattern given in desc-pattern
441 ".devscripts" value: SALSA_DESC (yes/no)
443 --desc-pattern
445 Repo description pattern. Default to "Debian package %p". "%p" is
446 replaced by repo name, while %P is replaced by repo name given in
447 command (may contains full path).
448 ".devscripts" value: SALSA_DESC_PATTERN
450 --email, --no-email, --disable-email
452 Enable, ignore or disable email-on-push.
453 ".devscripts" value: SALSA_EMAIL (yes/ignore/no, default: ignore)
455 --email-recipient
457 Email-on-push recipient. Can be multi valued:
458 $ salsa update_safe myrepo \
460 --email-recipient foo@foobar.org \
461 --email-recipient bar@foobar.org
462 If recipient value contains "%p", it is replaced by project name.
464 ".devscripts" value: SALSA_EMAIL_RECIPIENTS (use spaces to separate
466 multiples recipients)
467 --enable-issues, --no-enable-issues, --disable-issues,
469 --no-disable-issues
470 Enable, ignore or disable issues.
471 ".devscripts" values: SALSA_ENABLE_ISSUES (yes/ignore/no, default:
473 ignore)
474 --enable-mr, --no-enable-mr, --disable-mr, --no-disable-mr
476 Enable, ignore or disable merge requests.
477 ".devscripts" values: SALSA_ENABLE_MR (yes/ignore/no, default:
479 ignore)
480 --irc-channel
482 IRC channel for KGB or Irker. Can be used more than one time only
483 with --irker.
484 Important: channel must not include the first "#". If salsa finds a
486 channel starting with "#", it will consider that the channel starts
487 with 2 "#"!
488 ".devscript" value: SALSA_IRC_CHANNEL.
490 Multiple values must be space separated.
492 Since configuration files are read using sh, be careful when using
494 "#": you must enclose the channel with quotes, else sh will
495 consider it as a comment and will ignore this value.
496 --irker, --no-irker, --disable-irker
498 Enable, ignore or disable Irker service
499 ".devscripts" values: SALSA_IRKER (yes/ignore/no, default: ignore)
501 --irker-host
503 Irker host. Default: ruprecht.snow-crash.org
504 ".devscripts" value: SALSA_IRKER_HOST
506 --irker-port
508 Irker host. Default: empty (default value)
509 ".devscripts" value: SALSA_IRKER_PORT
511 --kgb, --no-kgb, --disable-kgb
513 Enable, ignore or disable KGB webhook.
514 ".devscripts" value: SALSA_KGB (yes/ignore/no, default: ignore)
516 --no-fail
518 Don't stop on error when using update_repo with --all.
519 ".devscripts" value: SALSA_NO_FAIL (yes/no)
521 --rename-head, --no-rename-head
523 Rename HEAD branch given by --source-branch into --dest-branch and
524 change "default branch" of project. Works only with update_repo.
525 ".devscripts" value: SALSA_RENAME_HEAD (yes/no)
527 --source-branch: default "master"
529 ".devscripts" value: SALSA_SOURCE_BRANCH
530 --dest-branch: default "debian/master"
532 ".devscripts" value: SALSA_DEST_BRANCH
533 --tagpending, --no-tagpending, --disable-tagpending
535 Enable, ignore or disable "tagpending" webhook.
536 ".devscripts" value: SALSA_TAGPENDING (yes/ignore/no, default:
538 ignore)
539 Merge requests options
541 --mr-title
542 Title for merge request. Default: last commit title.
543 --mr-desc
545 Description of new MR. Default:
546 empty if --mr-title is set
548 last commit description if any
549 --mr-dst-branch (or second command line argument)
550 Destination branch. Default to "master".
551 --mr-dst-project (or first command line argument)
553 Destination project. Default: project from which the current
554 project was forked; or, if not found, "upstream" value found using
555 git remote --verbose show; or using source project.
556 If --mr-dst-project is set to same, salsa will use source project
558 as destination.
559 --mr-src-branch
561 Source branch. Default: current branch.
562 --mr-src-project
564 Source project. Default: current project found using git remote
565 --verbose show.
566 --mr-allow-squash, --no-mr-allow-squash
568 Allow upstream project to squash your commits, this is the default.
569 ".devscripts" value: SALSA_MR_ALLOW_SQUASH (yes/no)
571 --mr-remove-source-branch, --no-mr-remove-source-branch
573 Remove source branch if merge request is accepted. Default: no.
574 ".devscripts" value: SALSA_MR_REMOVE_SOURCE_BRANCH (yes/no)
576 Options to manage other Gitlab instances
578 --api-url
579 GitLab API. Default: <https://salsa.debian.org/api/v4>.
580 ".devscripts" value: SALSA_API_URL
582 --git-server-url
584 Default to "git@salsa.debian.org:"
585 ".devscripts" value: SALSA_GIT_SERVER_URL
587 --irker-server-url
589 Default to "ircs://irc.oftc.net:6697/"
590 ".devscripts" value: SALSA_IRKER_SERVER_URL
592 --kgb-server-url
594 Default to <http://kgb.debian.net:9418/webhook/?channel=>
595 ".devscripts" value: SALSA_KGB_SERVER_URL
597 --tagpending-server-url
599 Default to <https://webhook.salsa.debian.org/tagpending/>
600 ".devscripts" value: SALSA_TAGPENDING_SERVER_URL
602 Configuration file example
604 Example to use salsa with <https://gitlab.ow2.org> (group "lemonldap-
606 ng"):
607 SALSA_TOKEN=`cat ~/.ow2-gitlab-token`
609 SALSA_API_URL=https://gitlab.ow2.org/api/v4
610 SALSA_GIT_SERVER_URL=git@gitlab.ow2.org:
611 SALSA_GROUP_ID=34
612 Then to use it, add something like this in your ".bashrc" file:
614 alias llng_admin='salsa --conffile ~/.salsa-ow2.conf'
616
618 dpt-salsa
619
621 Xavier Guimard <yadd@debian.org>
622
624 Copyright (C) 2018, Xavier Guimard <yadd@debian.org>
625 It contains code formely found in dpt-salsa (pkg-perl-tools) copyright
627 2018, gregor herrmann <gregoa@debian.org>.
628 This library is free software; you can redistribute it and/or modify it
630 under the terms of the GNU General Public License as published by the
631 Free Software Foundation; either version 2, or (at your option) any
632 later version.
633 This program is distributed in the hope that it will be useful, but
635 WITHOUT ANY WARRANTY; without even the implied warranty of
636 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
637 General Public License for more details.
638 You should have received a copy of the GNU General Public License along
640 with this program. If not, see <http://www.gnu.org/licenses/>.
641Debian Utilities 2019-01-12 SALSA(1)