# man > SALSA(1) [_SALSA_(1)](https://www.chedong.com/phpMan.php/man/SALSA/1/markdown) [_SALSA_(1)](https://www.chedong.com/phpMan.php/man/SALSA/1/markdown) ## NAME salsa - tool to manipulate salsa projects, repositories and group members ## SYNOPSIS # salsa salsa add_user developer foobar --group-id 2665 salsa delete_user foobar --group js-team salsa search_groups perl-team/modules salsa search_projects qa/qa salsa search_users yadd salsa update_user maintainer foobar --group js-team salsa whoami salsa checkout node-mongodb --group js-team salsa fork salsa fork --group js-team user/node-foo salsa last_ci_status js-team/nodejs salsa pipelines js-team/nodejs salsa mr debian/foo debian/master salsa push_repo . --group js-team --kgb --irc devscripts --tagpending salsa update_projects node-mongodb --group js-team --disable-kgb --desc \ --desc-pattern "Package %p" salsa update_safe --all --desc --desc-pattern "Debian package %p" \ --group js-team ## DESCRIPTION **salsa **is designed to create and configure projects and repositories on <> as well as to manage group members. A Salsa token is required, except for search* commands, and must be set in command line _(see_ _below)_, or in your configuration file _(~/.devscripts)_: SALSA_TOKEN=abcdefghi or SALSA_TOKEN=`cat ~/.token` or SALSA_TOKEN_FILE=~/.dpt.conf If you choose to link another file using SALSA_TOKEN_FILE, it must contain a line with one of (no differences): SALSA_PRIVATE_TOKEN=xxxx SALSA_TOKEN=xxxx This allows for example to use [**dpt**(1)](https://www.chedong.com/phpMan.php/man/dpt/1/markdown) configuration file (~/.dpt.conf) which contains: DPT_SALSA_PRIVATE_TOKEN=abcdefghi ## COMMANDS ### Managing users and groups ### add_user Add a user to a group. salsa --group js-group add_user guest foouser salsa --group-id 1234 add_user guest foouser salsa --group-id 1234 add_user maintainer 1245 First argument is the GitLab's access levels: guest, reporter, developer, maintainer, owner. **delete_user **or **del_user** Remove a user from a group. salsa --group js-team delete_user foouser salsa --group-id=1234 delete_user foouser ### join Request access to a group. salsa join js-team salsa join --group js-team salsa join --group-id 1234 ### list_groups List the subgroups for current group if group is set, otherwise will do the current user. **list_users **or **group** List users in a subgroup. Note, this does not include inherited or invited. salsa --group js-team list_users salsa --group-id 1234 list_users ### search_groups Search for a group using given string. Shows group ID and other information. salsa search_groups perl-team salsa search_groups perl-team/modules salsa search_groups 2666 ### search_users Search for a user using given string. Shows user ID and other information. salsa search_users yadd ### update_user Update a user's role in a group. salsa --group-id 1234 update_user guest foouser salsa --group js-team update_user maintainer 1245 First argument is the GitLab's access levels: guest, reporter, developer, maintainer, owner. ### whoami Gives information on the token owner. salsa whoami ### Managing projects One of "--group", "--group-id", "--user" or "--user-id" is required to manage projects. If both are set, salsa warns and only "--user"/"--user-id" is used. If none is given, salsa uses current user ID _(token_ _owner)_. **check_projects **or **check_repo** Verify that projects are configured as expected. It works exactly like **update_projects** except that it does not modify anything but just lists projects not well configured with found errors. salsa --user yadd --tagpending --kgb --irc=devscripts check_projects test salsa --group js-team check_projects --all salsa --group js-team --rename-head check_projects test1 test2 test3 **checkout **or **co** Clone a project's repository in current directory. If the directory already exists, update local repository. salsa --user yadd checkout devscripts salsa --group js-team checkout node-mongodb salsa checkout js-team/node-mongodb You can clone more than one repository or all repositories of a group or a user: salsa --user yadd checkout devscripts autodep8 salsa checkout yadd/devscripts js-team/npm salsa --group js-team checkout --all # All js-team active repositories salsa checkout --all-archived # All your repositories, including archived **create_project **or **create_repo** Create public empty project. If "--group"/"--group-id" is set, project is created in group directory, else in user directory. salsa --user yadd create_project test salsa --group js-team --kgb --irc-channel=devscripts create_project test **delete_project **or **del_repo** Delete a project. ### fork Forks a project in group/user repository and set "upstream" to original project. Example: $ salsa fork js-team/node-mongodb --verbose ... salsa.pl info: node-mongodb ready in node-mongodb/ $ cd node-mongodb $ git remote --verbose show origin :me/node-mongodb (fetch) origin :me/node-mongodb (push) upstream :js-team/node-mongodb (fetch) upstream :js-team/node-mongodb (push) For a group: salsa fork --group js-team user/node-foo ### forks List forks of project(s). salsa forks qa/qa debian/devscripts Project can be set using full path or using **--group**/**--group-id **or **--user**/**--user-id**, else it is searched in current user namespace. ### push Push relevant packaging refs to origin Git remote. To be run from packaging working directory. salsa push It pushes the following refs to the configured remote for the debian-branch or, falling back, to the "origin" remote: "master" branch (or whatever is set to debian-branch in gbp.conf) "upstream" branch (or whatever is set to upstream-branch in gbp.conf) "pristine-tar" branch tags named "debian/*" (or whatever is set to debian-tag in gbp.conf) tags named "upstream/*" (or whatever is set to upstream-tag in gbp.conf) all tags, if the package's source format is "3.0 (native)" **list_projects **or **list_repos **or **ls** Shows projects owned by user or group. If second argument exists, search only matching projects. salsa --group js-team list_projects salsa --user yadd list_projects foo* ### last_ci_status Displays the last continuous integration result. Use **--verbose **to see URL of pipeline when result isn't **success**. Unless **--no-fail **is set, **salsa last_ci_status **will stop on first "failed" status. salsa --group js-team last_ci_status --all --no-fail salsa --user yadd last_ci_status foo salsa last_ci_status js-team/nodejs This commands returns the number of "failed" status found. "success" entries are displayed using STDOUT while other are displayed _(with_ _details)_ using STDERR. Then you can easily see only failures using: salsa --group js-team last_ci_status --all --no-fail >/dev/null **pipeline_schedule **or **schedule** Control pipeline schedule. **pipeline_schedules **or **schedules** Lists current pipeline schedule items. You can use **--no-fail **and **--all **options here. **merge_request **or **mr** Creates a merge request. Suppose you created a fork using **salsa fork**, modify some things in a new branch using one commit and want to propose it to original project _(branch_ _"master")_. You just have to launch this in source directory: salsa merge_request Another example: salsa merge_request --mr-dst-project debian/foo --mr-dst-branch debian/master Or simply: salsa merge_request debian/foo debian/master Note that unless destination project has been set using command line, **salsa merge_request** will search it in the following order: using GitLab API: salsa will detect from where this project was forked using "upstream" origin else salsa will use source project as destination project To force salsa to use source project as destination project, you can use "same": salsa merge_request --mr-dst-project same # or salsa merge_request same New merge request will be created using last commit title and description. See **--mr-* **options for more. **merge_requests **or **mrs** List opened merge requests for project(s). salsa merge_requests qa/qa debian/devscripts Project can be set using full path or using **--group**/**--group-id **or **--user**/**--user-id**, else it is searched in current user namespace. ### protect_branch Protect/unprotect a branch. Protect # project branch merge push salsa --group js-team protect_branch node-mongodb master m d "merge" and "push" can be one of: **o**, **owner**: owner only **m**, **maintainer**: **o **+ maintainers allowed **d**, **developer**: **m **+ developers allowed **r**, **reporter**: **d **+ reporters allowed **g**, **guest**: **r **+ guest allowed Unprotect salsa --group js-team protect_branch node-mongodb master no ### protected_branches List protected branches: salsa --group js-team protected_branches node-mongodb ### push_repo Create a new project from a local Debian source directory configured with git. **push_repo **executes the following steps: gets project name using debian/changelog file; launches **git remote add upstream ...**; launches **create_project**; pushes local repository. Examples: salsa --user yadd push_repo ./test salsa --group js-team --kgb --irc-channel=devscripts push_repo . ### rename_branch Rename branch given in **--source-branch **with name given in **--dest-branch**. You can use **--no-fail**, **--all **and **--all-archived **options here. **search_projects **or **search_repo **or **search** Search for a project using given string. Shows name, owner ID and other information. salsa search_projects devscripts salsa search_projects debian/devscripts salsa search_projects 18475 **update_projects **or **update_repo** Configure projects using parameters given to command line. A project name has to be given unless **--all **or **--all-archived **is set. Prefer to use **update_safe**. salsa --user yadd --tagpending --kgb --irc=devscripts update_projects test salsa --group js-team update_projects --all salsa --group js-team --rename-head update_projects test1 test2 test3 salsa update_projects js-team/node-mongodb --kgb --irc debian-js By default when using **--all**, salsa will fail on first error. If you want to continue, set **--no-fail**. In this case, salsa will display a warning for each project that has fail but continue with next project. Then to see full errors, set **--verbose**. ### update_safe Launch **check_projects **and ask before launching **update_projects **(unless **--yes**). salsa --user yadd --tagpending --kgb --irc=devscripts update_safe test salsa --group js-team update_safe --all salsa --group js-team --rename-head update_safe test1 test2 test3 salsa update_safe js-team/node-mongodb --kgb --irc debian-js ### Other ### purge_cache Empty local cache. ## OPTIONS ### General options **--chdir **or **-C** Change directory before launching command: salsa --chdir ~/debian checkout debian/libapache2-mod-fcgid ### --cache-file File to store cached values. An empty value disables cache. Default: "~/.cache/salsa.json". ".devscripts" value: **SALSA_CACHE_FILE** ### --no-cache Disable cache usage. Same as **--cache-file ''** **--conf-file **or **--conffile** Add or replace default configuration files. This can only be used as the first option given on the command-line. Default: "/etc/devscripts.conf" and "~/.devscripts". replace: salsa --conf-file test.conf ... salsa --conf-file test.conf --conf-file test2.conf ... add: salsa --conf-file +test.conf ... salsa --conf-file +test.conf --conf-file +test2.conf ... If one **--conf-file **has no "+", default configuration files are ignored. **--no-conf **or **--noconf** Don't read any configuration files. This can only be used as the first option given on the command-line. ### --debug Enable debugging output. ### --group Team to use. Use "salsa search_groups name" to find it. If you want to use a subgroup, you have to set its full path: salsa --group perl-team/modules/packages check_projects lemonldap-ng ".devscripts" value: **SALSA_GROUP** Be careful when you use **SALSA_GROUP **in your ".devscripts" file. Every **salsa **command will be executed in group space, for example if you want to propose a little change in a project using **salsa fork **+ **salsa merge_request**, this "fork" will be done in group space unless you set a **--user**/**--user-id**. Prefer to use an alias in your ".bashrc" file. Example: alias jsteam_admin="salsa --group js-team" or alias jsteam_admin="salsa --conf-file ~/.js.conf or to use both .devscripts and .js.conf: alias jsteam_admin="salsa --conf-file +~/.js.conf then you can fix **SALSA_GROUP **in "~/.js.conf" To enable bash completion for your alias, add this in your .bashrc file: _completion_loader salsa complete -F _salsa_completion jsteam_admin ### --group-id Group ID to use. Use "salsa search_groups name" to find it. ".devscripts" value: **SALSA_GROUP_ID** Be careful when you use **SALSA_GROUP_ID **in your ".devscripts" file. Every **salsa **command will be executed in group space, for example if you want to propose a little change in a project using **salsa fork **+ **salsa merge_request**, this "fork" will be done in group space unless you set a **--user**/**--user-id**. Prefer to use an alias in your ".bashrc" file. Example: alias jsteam_admin="salsa --group-id 2666" or alias jsteam_admin="salsa --conf-file ~/.js.conf then you can fix **SALSA_GROUP_ID **in "~/.js.conf". ### --help Displays this manpage. **--info **or **-i** Prompt before sensible changes. ".devscripts" value: **SALSA_INFO **(yes/no) ### --path Repository path. Default to group or user path. ".devscripts" value: **SALSA_REPO_PATH** ### --token Token value (see above). ### --token-file File to find token (see above). ### --user Username to use. If neither **--group**, **--group-id**, **--user **or **--user-id **is set, salsa uses current user ID (corresponding to salsa private token). ### --user-id User ID to use. Use "salsa search_users name" to find one. If neither **--group**, **--group-id**, **--user **or **--user-id **is set, salsa uses current user ID (corresponding to salsa private token). ".devscripts" value: **SALSA_USER_ID** ### --verbose Enable verbose output. ### --yes Never ask for consent. ".devscripts" value: **SALSA_YES **(yes/no) ### List/search project options **--archived**, **--no-archived** Instead of looking to active projects, list or search in archived projects. Note that you can't have both archived and unarchived projects in the same request. Default: no _(ie_ _--no-archived)_. ".devscripts" value: **SALSA_ARCHIVED **(yes/no) ### Update/create project options **--all**, **--all-archived** When set, all projects of group/user are affected by command. **--all **will filter all active projects, whereas **--all-archived **will include active and archived projects. **--skip**, **--no-skip** Ignore project with **--all **or **--all-achived**. Example: salsa update_projects --tagpending --all --skip qa --skip devscripts To set multiples values, use spaces. Example: SALSA_SKIP=qa devscripts Using **--no-skip **will ignore any projects to be skipped and include them. ".devscripts" value: **SALSA_SKIP** **--skip-file** Ignore projects in this file (1 project per line). salsa update_projects --tagpending --all --skip-file ~/.skip ".devscripts" value: **SALSA_SKIP_FILE** ### --build-timeout The maximum amount of time, in seconds, that a job can run. Default: 3600 (60 minutes). salsa update_safe myrepo --build-timeout 3600 ".devscripts" value: **SALSA_BUILD_TIMEOUT** ### --avatar-path Path to an image for the project's avatar. If path value contains "%p", it is replaced by project name. ".devscripts" value: **SALSA_AVATAR_PATH** ### --ci-config-path Configure configuration file path of GitLab CI. Default: empty. Example: salsa update_safe --ci-config-path recipes/debian.yml@salsa-ci-team/pipeline debian/devscripts ".devscripts" value: **SALSA_CI_CONFIG_PATH** **--desc**, **--no-desc** Configure a project's description using pattern given in **desc-pattern**. ".devscripts" value: **SALSA_DESC **(yes/no) ### --desc-pattern Project's description pattern. "%p" is replaced by project's name, while "%P" is replaced by project's name given in command (may contains full path). Default: "Debian package %p". ".devscripts" value: **SALSA_DESC_PATTERN** **--email**, **--no-email**, **--disable-email** Enable, ignore or disable email-on-push. ".devscripts" value: **SALSA_EMAIL **(yes/ignore/no, default: ignore) ### --email-recipient Email-on-push recipient. Can be multi valued: $ salsa update_safe myrepo \ --email-recipient \ --email-recipient If recipient value contains "%p", it is replaced by project name. ".devscripts" value: **SALSA_EMAIL_RECIPIENTS **(use spaces to separate multiples recipients) ### --analytics Set analytics feature with permissions. ".devscripts" value: **SALSA_ENABLE_ANALYTICS **(yes/private/no, default: yes) ### --auto-devops Set auto devops feature. ".devscripts" value: **SALSA_ENABLE_AUTO_DEVOPS **(yes/no, default: yes) ### --container Set container feature with permissions. ".devscripts" value: **SALSA_ENABLE_CONTAINER **(yes/private/no, default: yes) ### --environments Set environments feature with permissions. ".devscripts" value: **SALSA_ENABLE_ENVIRONMENTS **(yes/private/no, default: yes) ### --feature-flags Set feature flags feature with permissions. ".devscripts" value: **SALSA_ENABLE_FEATURE_FLAGS **(yes/private/no, default: yes) ### --forks Set forking a project feature with permissions. ".devscripts" value: **SALSA_ENABLE_FORKS **(yes/private/no, default: yes) ### --infrastructure Set infrastructure feature with permissions. ".devscripts" value: **SALSA_ENABLE_INFRASTRUCTURE **(yes/private/no, default: yes) ### --issues Set issues feature with permissions. ".devscripts" value: **SALSA_ENABLE_ISSUES **(yes/private/no, default: yes) ### --jobs Set jobs feature with permissions. ".devscripts" value: **SALSA_ENABLE_JOBS **(yes/private/no, default: yes) ### --lfs Set Large File Storage (LFS) feature. ".devscripts" value: **SALSA_ENABLE_LFS **(yes/no, default: yes) ### --mr Set merge requests feature with permissions. ".devscripts" value: **SALSA_ENABLE_MR **(yes/private/no, default: yes) ### --monitor Set monitor feature with permissions. ".devscripts" value: **SALSA_ENABLE_MONITOR **(yes/private/no, default: yes) ### --packages Set packages feature. ".devscripts" value: **SALSA_ENABLE_PACKAGES **(yes/no, default: yes) ### --pages Set pages feature with permissions. ".devscripts" value: **SALSA_ENABLE_PAGES **(yes/private/no, default: yes) ### --releases Set releases feature with permissions. ".devscripts" value: **SALSA_ENABLE_RELEASES **(yes/private/no, default: yes) **--enable-remove-source-branch**, **--disable-remove-source-branch** Enable or disable deleting source branch option by default for all new merge requests. ".devscripts" value: **SALSA_REMOVE_SOURCE_BRANCH **(yes/no, default: yes) ### --repo Set the project's repository feature with permissions. ".devscripts" value: **SALSA_ENABLE_REPO **(yes/private/no, default: yes) ### --request-access Allow users to request member access. ".devscripts" value: **SALSA_REQUEST_ACCESS **(yes/no) ### --requirements Set requirements feature with permissions. ".devscripts" value: **SALSA_ENABLE_REQUIREMENTS **(yes/private/no, default: yes) ### --security-compliance Enable or disabled Security and Compliance feature. ".devscripts" value: **SALSA_ENABLE_SECURITY_COMPLIANCE **(yes/no) ### --service-desk Allow service desk feature. ".devscripts" value: **SALSA_ENABLE_SERVICE_DESK **(yes/no) ### --snippets Set snippets feature with permissions. ".devscripts" value: **SALSA_ENABLE_SNIPPETS **(yes/private/no, default: yes) ### --wiki Set wiki feature with permissions. ".devscripts" value: **SALSA_ENABLE_WIKI **(yes/private/no, default: yes) ### --irc-channel IRC channel for KGB or Irker. Can be used more than one time only with **--irker**. **Important**: channel must not include the first "#". If salsa finds a channel starting with "#", it will consider that the channel starts with 2 "#"! ".devscript" value: **SALSA_IRC_CHANNEL** Multiple values must be space separated. Since configuration files are read using **sh**, be careful when using "#": you must enclose the channel with quotes, else **sh **will consider it as a comment and will ignore this value. **--irker**, **--no-irker**, **--disable-irker** Enable, ignore or disable Irker service. ".devscripts" value: **SALSA_IRKER **(yes/ignore/no, default: ignore) ### --irker-host Irker host. Default: ruprecht.snow-crash.org. ".devscripts" value: **SALSA_IRKER_HOST** ### --irker-port Irker port. Default: empty (default value). ".devscripts" value: **SALSA_IRKER_PORT** **--kgb**, **--no-kgb**, **--disable-kgb** Enable, ignore or disable KGB webhook. ".devscripts" value: **SALSA_KGB **(yes/ignore/no, default: ignore) ### --kgb-options List of KGB enabled options (comma separated). Default: issues_events, merge_requests_events, note_events, pipeline_events, push_events, tag_push_events, wiki_page_events, enable_ssl_verification $ salsa update_safe debian/devscripts --kgb --irc-channel devscripts \ --kgb-options 'merge_requests_events,issues_events,enable_ssl_verification' List of available options: confidential_comments_events, confidential_issues_events, confidential_note_events, enable_ssl_verification, issues_events, job_events, merge_requests_events, note_events, pipeline_events, tag_push_events, wiki_page_events ".devscripts" value: **SALSA_KGB_OPTIONS** ### --no-fail Don't stop on error when using **update_projects **with **--all **or **--all-archived **when set to yes. ".devscripts" value: **SALSA_NO_FAIL **(yes/no, default: no) **--rename-head**, **--no-rename-head** Rename HEAD branch given by **--source-branch **into **--dest-branch **and change "default branch" of project. Works only with **update_projects**. ".devscripts" value: **SALSA_RENAME_HEAD **(yes/no) **--source-branch** Default: "master". ".devscripts" value: **SALSA_SOURCE_BRANCH** **--dest-branch** Default: "debian/master". ".devscripts" value: **SALSA_DEST_BRANCH** **--tagpending**, **--no-tagpending**, **--disable-tagpending** Enable, ignore or disable "tagpending" webhook. ".devscripts" value: **SALSA_TAGPENDING **(yes/ignore/no, default: ignore) ### Pipeline schedules ### --schedule-desc Description of the pipeline schedule. ### --schedule-ref Branch or tag name that is triggered. ### --schedule-cron Cron schedule. Example: 0 1 * * *. ### --schedule-tz Time zone to run cron schedule. Default: UTC. **--schedule-enable**, **--schedule-disable** Enable/disable the pipeline schedule to run. Default: disabled. ### --schedule-run Trigger **--schedule-desc **scheduled pipeline to run immediately. Default: false. ### --schedule-delete Delete **--schedule-desc **pipeline schedule. ### Merge requests options ### --mr-title Title for merge request. Default: last commit title. ### --mr-desc Description of new MR. Default: empty if **--mr-title **is set last commit description if any **--mr-dst-branch **(or second command line argument) Destination branch. Default: "master". **--mr-dst-project **(or first command line argument) Destination project. Default: project from which the current project was forked; or, if not found, "upstream" value found using **git remote --verbose show**; or using source project. If **--mr-dst-project **is set to **same**, salsa will use source project as destination. ### --mr-src-branch Source branch. Default: current branch. ### --mr-src-project Source project. Default: current project found using **git remote --verbose show**. **--mr-allow-squash**, **--no-mr-allow-squash** Allow upstream project to squash your commits, this is the default. ".devscripts" value: **SALSA_MR_ALLOW_SQUASH **(yes/no) **--mr-remove-source-branch**, **--no-mr-remove-source-branch** Remove source branch if merge request is accepted. Default: no. ".devscripts" value: **SALSA_MR_REMOVE_SOURCE_BRANCH **(yes/no) ### Options to manage other GitLab instances ### --api-url GitLab API. Default: <>. ".devscripts" value: **SALSA_API_URL** ### --git-server-url Default: ":". ".devscripts" value: **SALSA_GIT_SERVER_URL** ### --irker-server-url Default: "ircs://irc.oftc.net:6697/". ".devscripts" value: **SALSA_IRKER_SERVER_URL** ### --kgb-server-url Default: <=>. ".devscripts" value: **SALSA_KGB_SERVER_URL** ### --tagpending-server-url Default: <>. ".devscripts" value: **SALSA_TAGPENDING_SERVER_URL** _Configuration_ _file_ _example_ Example to use salsa with <> (group "lemonldap-ng"): SALSA_TOKEN=`cat ~/.ow2-gitlab-token` SALSA_API_URL= SALSA_GIT_SERVER_URL=: SALSA_GROUP_ID=34 Then to use it, add something like this in your ".bashrc" file: alias llng_admin='salsa --conffile ~/.salsa-ow2.conf' ## SEE ALSO ### dpt-salsa ## AUTHOR Xavier Guimard <> ## COPYRIGHT AND LICENSE Copyright (C) 2018, Xavier Guimard <> It contains code formerly found in dpt-salsa _(pkg-perl-tools)_ copyright 2018, gregor herrmann <>. This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <>. Debian Utilities 2026-02-25 [_SALSA_(1)](https://www.chedong.com/phpMan.php/man/SALSA/1/markdown)