SALSA(1)

NAME
salsa - tool to manipulate salsa projects, repositories and group members

SYNOPSIS
  # salsa <command> <parameters> <options>
  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 <https://salsa.debian.org> 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):

  <anything>SALSA_PRIVATE_TOKEN=xxxx
  <anything>SALSA_TOKEN=xxxx

This allows for example to use dpt(1) 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          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)"
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 <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 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 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)

--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: <https://salsa.debian.org/api/v4>.

    ".devscripts" value: SALSA_API_URL

--git-server-url
    Default: "git@salsa.debian.org:".

    ".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: <https://kgb.debian.net/webhook/?channel=>.

    ".devscripts" value: SALSA_KGB_SERVER_URL

--tagpending-server-url
    Default: <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'

SEE ALSO
dpt-salsa

AUTHOR
Xavier Guimard <yadd@debian.org>

COPYRIGHT AND LICENSE
Copyright (C) 2018, Xavier Guimard <yadd@debian.org>

It contains code formerly found in dpt-salsa (pkg-perl-tools) copyright 2018, gregor herrmann <gregoa@debian.org>.

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 <http://www.gnu.org/licenses/>.