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.

del_user

Remove a user from a group

  salsa --group js-team del_user foouser
  salsa --group-id=1234 del_user foouser
    

list_groups

List sub groups of current one if group is set, groups of current user else.

group

Show group members.

  salsa --group js-team group
  salsa --group-id 1234 group
    

search_group

Search for a group using given string. Shows group id and other information.

  salsa search_group perl-team
  salsa search_group perl-team/modules
  salsa search_group 2666
    

search_user

Search for a user using given string. Shows user id and other information.

  salsa search_user yadd
    

update_user

Update user 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 repositories

One of "--group", "--group-id", "--user" or "--user-id" is required to manage repositories. 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_repo

Verify that repo(s) are well configured. It works exactly like update_repo 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_repo test
  salsa --group js-team check_repo --all
  salsa --group js-team --rename-head check_repo test1 test2 test3
    

checkout or co

Clone repo in current dir. If directory already exists, update local repo.

  salsa --user yadd co devscripts
  salsa --group js-team co node-mongodb
  salsa co js-team/node-mongodb
    

You can clone more than one repository or all repositories of a group or a user:

  salsa --user yadd co devscripts autodep8
  salsa co yadd/devscripts js-team/npm
  salsa --group js-team co --all           # All js-team repos
  salsa co --all                           # All your repos
    

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_repo test
  salsa --group js-team --kgb --irc-channel=devscripts create_repo test
    

del_repo

Delete a repository.

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          git@salsa.debian.org:me/node-mongodb (fetch)
  origin          git@salsa.debian.org:me/node-mongodb (push)
  upstream        git@salsa.debian.org:js-team/node-mongodb (fetch)
  upstream        git@salsa.debian.org: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.

ls or list_repos

Shows projects owned by user or group. If second argument exists, search only matching projects

  salsa --group js-team list_repos
  salsa --user yadd list_repos foo*
    

merge_request, 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 mr
    

Other example:

  salsa mr --mr-dst-project debian/foo --mr-dst-branch debian/master
    

or simply

  salsa mr 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:

  salsa mr --mr-dst-project same
  # or
  salsa mr same

merge_requests, mrs

List opened merge requests for project(s)

  salsa mrs 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.

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:

  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 and --all options here.

search, search_project, search_repo

Search for a project using given string. Shows name, owner id and other information.

  salsa search devscripts
  salsa search debian/devscripts
  salsa search 18475
    

update_repo

Configure repo(s) using parameters given to command line. A repo name has to be given unless --all is set. Prefer to use update_safe.

  salsa --user yadd --tagpending --kgb --irc=devscripts update_repo test
  salsa --group js-team update_repo --all
  salsa --group js-team --rename-head update_repo test1 test2 test3
  salsa update_repo 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_repo and ask before launching update_repo (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.

General options

-C, --chdir

Change directory before launching command

  salsa -C ~/debian co debian/libapache2-mod-fcgid
    

--cache-file

File to store cached values. Default to ~/.cache/salsa.json. An empty value disables cache.

".devscripts" value: SALSA_CACHE_FILE

--no-cache

Disable cache usage. Same as --cache-file ''

--conffile, --conf-file

Add or replace default configuration files ("/etc/devscripts.conf" and "~/.devscripts"). This can only be used as the first option given on the command-line.

--no-conf, --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_group 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_repo 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 mr, 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
    

then you can fix SALSA_GROUP in "~/.js.conf"

--group-id

Group id to use. Use "salsa search_group 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 mr, 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

-i, --info

Prompt before sensible changes.

".devscripts" value: SALSA_INFO (yes/no)

--path

Repo 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_user 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)

Update/create repo options

--all

When set, all project of group/user are affected by command.

--ci-config-path

Configure configuration file path of GitLab CI. Default: empty. Example:

  salsa update_safe --ci-config-path debian/.gitlab-ci.yml debian/devscripts
    

".devscripts" value: SALSA_CI_CONFIG_PATH

--desc --no-desc

Configure repo description using pattern given in desc-pattern

".devscripts" value: SALSA_DESC (yes/no)

--desc-pattern

Repo description pattern. Default to "Debian package %p". "%p" is replaced by repo name, while "%P" is replaced by repo name given in command (may contains full path).

".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 foo@foobar.org \
        --email-recipient bar@foobar.org
    

If recipient value contains "%p", it is replaced by project name.

".devscripts" value: SALSA_EMAIL_RECIPIENTS (use spaces to separate multiples recipients)

--enable-issues, --no-enable-issues, --disable-issues, --no-disable-issues

Enable, ignore or disable issues.

".devscripts" values: SALSA_ENABLE_ISSUES (yes/ignore/no, default: ignore)

--enable-mr, --no-enable-mr, --disable-mr, --no-disable-mr

Enable, ignore or disable merge requests.

".devscripts" values: SALSA_ENABLE_MR (yes/ignore/no, default: ignore)

--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" values: 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

  $ 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_repo with --all.

".devscripts" value: SALSA_NO_FAIL (yes/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_repo.

".devscripts" value: SALSA_RENAME_HEAD (yes/no)

--tagpending, --no-tagpending, --disable-tagpending

Enable, ignore or disable "tagpending" webhook.

".devscripts" value: SALSA_TAGPENDING (yes/ignore/no, default: ignore)

Merge requests options

--mr-title

Title for merge request. Default: last commit title.

--mr-desc

Description of new MR. Default:

--mr-dst-branch (or second command line argument)

Destination branch. Default to "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: <https://salsa.debian.org/api/v4>.

".devscripts" value: SALSA_API_URL

--git-server-url

Default to "git@salsa.debian.org:"

".devscripts" value: SALSA_GIT_SERVER_URL

--irker-server-url

Default to "ircs://irc.oftc.net:6697/"

".devscripts" value: SALSA_IRKER_SERVER_URL

--kgb-server-url

Default to <http://kgb.debian.net:9418/webhook/?channel=>

".devscripts" value: SALSA_KGB_SERVER_URL

--tagpending-server-url

Default to <https://webhook.salsa.debian.org/tagpending/>

".devscripts" value: SALSA_TAGPENDING_SERVER_URL

Configuration file example

Example to use salsa with <https://gitlab.ow2.org> (group "lemonldap-ng"):

  SALSA_TOKEN=`cat ~/.ow2-gitlab-token`
  SALSA_API_URL=https://gitlab.ow2.org/api/v4
  SALSA_GIT_SERVER_URL=git@gitlab.ow2.org:
  SALSA_GROUP_ID=34

Then to use it, add something like this in your ".bashrc" file:

  alias llng_admin='salsa --conffile ~/.salsa-ow2.conf'