salsa - Man Page

join

Request access to a group.

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

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

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 active repos
  salsa co --all-archived                  # All your repos including archived

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.

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)"

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*

last_ci_status or ci

Displays 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

Control pipeline schedule

pipelines, schedules

Lists current pipeline schedule items.

You can use --no-fail and --all options here.

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:

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 mr --mr-dst-project same
  # or
  salsa mr same

New merge request will be created using last commit title and description.

See --mr-* options for more.

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.

Set protection

  #                                    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_repo;

pushes local repo.

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, 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 or --all-archived 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

purge_cache

Empty local cache.

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

replace:

  salsa --conf-file test.conf <command>...
  salsa --conf-file test.conf --conf-file test2.conf  <command>...

add:

  salsa --conf-file +test.conf <command>...
  salsa --conf-file +test.conf --conf-file +test2.conf  <command>...

If one --conf-file has no +, default configuration files are ignored.

--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

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_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)

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

--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: ignore project with --all or --all-achived. Example:

  salsa update_repo --tagpending --all --skip qa --skip devscripts

.devscripts value: SALSA_SKIP. To set multiples values, use spaces. Example

  SALSA_SKIP=qa devscripts

--skip-file: ignore projects in this file (1 project per line)

  salsa update_repo --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 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)

--issues

Set issues feature with permissions.

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

--repo

Set repository feature with permissions.

.devscripts values: SALSA_ENABLE_REPO (yes/private/no, default: yes)

--mr

Set merge requests feature with permissions.

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

--forks,  --forks-mr

Set forking a repository feature with permissions.

.devscripts values: SALSA_ENABLE_FORKS (yes/private/no, default: yes)

--lfs

Set Large File Storage (LFS) feature.

.devscripts values: SALSA_ENABLE_LFS (yes/no, default: yes)

--packages

Set packages feature.

.devscripts values: SALSA_ENABLE_PACKAGING (yes/no, default: yes)

--jobs

Set jobs feature with permissions.

.devscripts values: SALSA_ENABLE_JOBS (yes/private/no, default: yes)

--container

Set container feature with permissions.

.devscripts values: SALSA_ENABLE_CONTAINER (yes/private/no, default: yes)

--analytics

Set analytics feature with permissions.

.devscripts values: SALSA_ENABLE_ANALYTICS (yes/private/no, default: yes)

--requirements

Set requirements feature with permissions.

.devscripts values: SALSA_ENABLE_REQUIREMENTS (yes/private/no, default: yes)

--wiki

Set wiki feature with permissions.

.devscripts values: SALSA_ENABLE_WIKI (yes/private/no, default: yes)

--snippets

Set snippets feature with permissions.

.devscripts values: SALSA_ENABLE_SNIPPETS (yes/private/no, default: yes)

--pages

Set pages feature with permissions.

.devscripts values: SALSA_ENABLE_PAGES (yes/private/no, default: yes)

--releases

Set releases feature with permissions.

.devscripts values: SALSA_ENABLE_RELEASES (yes/private/no, default: yes)

--auto-devops

Set auto devops feature.

.devscripts values: SALSA_ENABLE_AUTO_DEVOPS (yes/no, default: yes)

--request-acc

Set request access feature.

.devscripts values: SALSA_ENABLE_REQUEST_ACC (yes/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 values: SALSA_REMOVE_SOURCE_BRANCH (yes/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 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, 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_repo with --all or --all-archived.

.devscripts value: SALSA_NO_FAIL (yes/no)

--request-access

Allow users to request member access.

.devscripts value: SALSA_REQUEST_ACCESS (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)

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

--schedule-desc

Description of the pipeline schedule.

--schedule-ref

Branch or tag name that is triggered.

--schedule-cron

Cron schedule, for 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:

--schedule-delete

Delete --schedule-desc pipeline schedule

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

--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'