salsa - tool to manipulate salsa repositories and group members
# salsa <command> <args>
salsa whoami
salsa search_project devscripts
salsa search_project qa/qa
salsa search_group js-team
salsa search_group perl-team/modules
salsa search_user yadd
salsa push_repo . --group js-team --kgb --irc devscripts --tagpending
salsa update_repo node-mongodb --group js-team --disable-kgb --desc \
--desc-pattern "Package %p"
salsa update_repo js-team/node-mongodb --kgb --irc debian-js
salsa update_safe --all --desc --desc-pattern "Debian package %p" \
--group js-team
salsa checkout node-mongodb --group js-team
salsa checkout js-team/node-mongodb
salsa add_user developer foobar --group-id 2665
salsa update_user maintainer foobar --group js-team
salsa del_user foobar --group js-team
salsa last_ci_status js-team/nodejs
salsa pipelines js-team/nodejs
salsa is designed to create and configure repositories on
<
https://salsa.debian.org> and manage users of groups.
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
- 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 oder 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
- Löscht ein Depot.
- 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 [email protected]:me/node-mongodb (fetch)
origin [email protected]:me/node-mongodb (push)
upstream [email protected]:js-team/node-mongodb (fetch)
upstream [email protected]: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 oder 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
Weiteres Beispiel:
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.
Beispiele:
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
- Standard-Konfigurationsdateien hinzufügen oder
ersetzen ("/etc/devscripts.conf" und "~/.devscripts").
Dies kann nur als erste auf der Befehlszeile angegebene Option benutzt
werden.
- 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
- liest keine Konfigurationsdateien. Dies kann nur als erste
auf der Befehlszeile angegebene Option benutzt werden.
- --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-Wert (siehe oben).
- --token-file
- Datei mit Token (siehe oben).
- --user
- Benutzername. Wenn weder --group, --group-id,
--user noch --user-id gesetzt sind, benutzt salsa die
aktuelle Benutzer-Id (die zu dem privaten Salsa-Token gehört).
- --user-id
- Benutzer-Id. Benutzen Sie "salsa search_user
name" um eine zu finden. Wenn weder --group,
--group-id, --user noch --user-id gesetzt sind,
benutzt salsa die aktuelle Benutzer-Id (die zu dem privaten Salsa-Token
gehört).
".devscripts" value: SALSA_USER_ID
- --verbose
- Erzeugt eine detaillierte Ausgabe.
- --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 [email protected] \
--email-recipient [email protected]
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. Standardwert:
<https://salsa.debian.org/api/v4>.
".devscripts" value: SALSA_API_URL
- --git-server-url
- Default to "[email protected]:"
".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
[email protected]:
SALSA_GROUP_ID=34
Then to use it, add something like this in your ".bashrc" file:
alias llng_admin='salsa --conffile ~/.salsa-ow2.conf'
dpt-salsa
Xavier Guimard <
[email protected]>
Copyright (C) 2018, Xavier Guimard <
[email protected]>
It contains code formerly found in dpt-salsa
(pkg-perl-tools) copyright
2018, gregor herrmann <
[email protected]>.
Dieses Programm ist freie Software; Sie können es unter den Bedingungen
der GNU General Public License, Version 2 oder (nach Ihrer Wahl) neuer, wie
sie von der Free Software Foundation veröffentlicht wurde, weitergeben
und/oder ändern.
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/>.