openSUSE:Git Packaging Workflow
Important: This document assumes you have also read the OBS to Git page. For command-line contributors, see the git-obs workflow section for streamlined package management. To learn about known issues see the dedicated page.
Prerequisites
OSC Version Requirements
Ensure you're running osc version 1.15.0 or later. Earlier versions may contain bugs in the osc fork
functionality. For example, Issue #1767 or Issue #1760.
For Leap users: Add the openSUSE:Tools
repo to get the latest osc:
zypper ar -f obs://openSUSE:Tools tools
Command comparison with the old workflow
Package sources are maintained in Git. Make sure to clone with SSH and have the SSH key in your Gitea profile to be able to push changes.
Old command | New command | Explanation |
---|---|---|
osc add file |
git add file |
Add a file |
osc vc |
osc vc |
Changelog |
osc ci |
git commit; git push |
Push changes to remote |
osc build |
osc build |
Build package |
osc branch |
osc fork |
Create fork on gitea and OBS build setup |
osc mkpac |
obs-git-init |
Create or update git repo |
osc meta prjconf |
vi _config |
Edit the â_configâ file in your project git |
Example update workflow
The following example shows the workflow for updating a package as a maintainer:
### As a maintainer, you may want to work directly in your repository:
git clone gitea@src.opensuse.org:xmpp/libstrophe.git
### If you are not the maintainer, you will not have write permission later on. So you may want
### to fork instead the repository and setup a build project. You can create this with one step:
osc fork network:messaging:xmpp libstrophe
osc co home:username:branches:network:messaging:xmpp/libstrophe # this is actually doing a git clone
cd libstrophe
### Should use main branch for Git devel projects.
git checkout -b main
vi *.spec
git rm *tar.xz
osc service localrun download_files
git add *tar.xz
osc vc
### Note: by default, this builds against openSUSE:Factory and not project
osc build --alternative-project=network:messaging:xmpp
git checkout main
git add *.spec *.changes *.tar.xz
git commit -m "Update to version ABC"
git push
osc results network:messaging:xmpp/libstrophe
osc sr network:messaging:xmpp/libstrophe openSUSE:Factory
Running osc fork
will print helpful output:
osc fork network:messaging:xmpp libstrophe
Using the following Gitea settings:
* Config path: /home/username/.config/tea/config.yml
* Login (name of the entry in the config file): obs
* URL: https://src.opensuse.org
* User: user1
Forking git repo xmpp/libstrophe ...
* Fork created: user1/libstrophe
Forking OBS package network:messaging:xmpp/libstrophe ...
* OBS apiurl: https://api.opensuse.org
* Fork created: home:user1:branches:network:messaging:xmpp/libstrophe
* scmsync URL: https://src.opensuse.org/user1/libstrophe#main
Here we can see that it actually creates a fork on Gitea, and a project branch on OBS so you can test build it.
As a maintainer we could also just:
git clone https://src.opensuse.org/xmpp/libstrophe.git
cd libstrophe # and do the changes as above
osc sr network:messaging:xmpp/libstrophe openSUSE:Factory # and still submit by mentioning the OBS project
We could also use tea
or git-obs
to just create a fork on Gitea without a project branch on OBS for building. Or we could follow the AGit workflow. Which will be explained below.
Example submission workflow
Upon trying to submit packages from an OBS home: project to a Git managed devel project you will receive an error message like the following:
$ osc sr home:mnhauke dnscontrol server:dns
Server returned an error: HTTP Error 403: Forbidden
The target project server:dns is managed in an external SCM: https://src.opensuse.org/dns/_ObsPrj.git#master
Follow these steps instead:
1. Log in to https://src.opensuse.org/ and use the web UI or tea
command line to create a blank repository under your user
2. Clone the blank repository to your local machine: git clone gitea@src.opensuse.org:$USER/$package.git
3. Check out the package from your home: project: osc co home:$USER $package
4. Use something like cp
or rsync
to copy the files from the osc checkout directory into the empty Git repository directory
5. Use the regular Git process to track and push your initial import:
git add -a
git status
git diff --cached
git commit -m 'Initial import'
git push $remote main
6. Find the maintainers of the relevant devel project: osc maintainer server:dns
7. Contact the maintainers (for example using a mass email) and ask them to please transfer the repository from your user space into their organization
Contributing to a package as a non-maintainer
Contributors now send pull requests on Gitea instead of submit requests to devel projects on OBS.
You can handle pull requests either via the Gitea Web user interface on src.opensuse.org or use git-obs
(which is installed automatically via osc
).
Contributors can use the workflow to "fork" a repository to their home organization, make changes and send a pull request. This workflow is already familiar to GitHub users. Another way to submit changes to a package where you are not a maintainer is to use the AGit workflow.
To sum it up: If you want to contribute to a package for which you are not set as maintainer, you have several options:
- Gitea
- Fork in Gitea
- Gitea Web UI
- Gitea command-line tool
tea
- git-obs
- Make your changes and git push
- Create a pull request
- AGit workflow
- Clone the package
- Push to a special branch, and a PR will be created automatically
When a user creates a pull request to the package repository, the autogits-devel
bot automatically creates a second pull request to the project repository _ObsPrj
.
In the _ObsPrj
pull request, the autogits_obs_staging_bot
bot provides a link to an OBS build project where the packages are built. The bot also posts the build results as a comment on the original PR. If the title of the pull request is prefixed with WIP:
, the automated workflow is not triggered.
The maintainer can then review the submitted changes. After the maintainer approves the PR, the bot automatically merges it. Pull requests from maintainers are automatically merged if the build is successful.
Git-obs workflow
Initial Setup
Log into Gitea and go to https://src.opensuse.org/user/settings/applications and create a new token.
Configure git-obs with your credentials:
# Configure login
git-obs login add --url=https://src.opensuse.org --user=... obs --set-as-default
# Upload an existing ssh key to Gitea
git-obs ssh-key add --key-path=~/.ssh/id_rsa.pub
# List ssh keys associated with Gitea account
git-obs ssh-key list
Submit a pull request:
# Fork a package:
git-obs repo fork <develprj>/<package>
# Clone the forked package:
git-obs repo clone <owner>/<package> [--no-ssh-strict-host-key-checking]
# Make change
cd <package>
git remote -v
git switch <branch>
git branch <new-branch>
# Alternatively: git branch for/<target-branch>/<feature-name>
# Make changes
git commit
git push
# Create a pull request
git-obs pr create [--title=...] [--description=...] [--target-branch=...]
Review a pull request:
git-obs pr review [<owner>/<repo>#<number> ...]
AGit workflow
This has the advantage that you don't need to fork a package before contributing. This also means we don't waste space in case you forget to clean it up after your contribution. See AGit documentation for details.
git clone https://src.opensuse.org/lxde/parcellite
vi *.spec *.changes
git commit -m "Update"
git push origin main:refs/for/main/my_update -o title="Update to 123"
Reviewing build results and submitting to Factory
Build results can be viewed on OBS:
osc results network:messaging:xmpp/libstrophe
Additionally, the autogits_obs_staging_bot
bot will post the build results as a comment on the created pull request.
Submissions to openSUSE:Factory are not yet managed through Git/Gitea. This process is still handled by osc. Therefore, after your changes are committed to the Git project or a PR is accepted, you must create a submit request to Factory. For example, to submit the libstrophe package, execute the following command:
osc sr network:messaging:xmpp/libstrophe openSUSE:Factory
Finding a package's devel project in Factory
Currently, a package in openSUSE:Factory doesn't show where the devel project for that package is. This will be improved in the future. The interim solution is to locate the development project by searching for the package name in pkgs/_meta/devel_packages.
Visualizing build results
http://br.opensuse.org/ creates an overview of build results.
Use https://br.opensuse.org/status/PRJ/PKG/<repo>/<arch>
where repo and arch are optional.
For example:
- https://br.opensuse.org/status/devel:languages:lua/lua54
- https://br.opensuse.org/status/devel:languages:lua/lua54/openSUSE_Tumbleweed/aarch64
This can be added to your packages README.md
:
Devel project build status:

Tips and best practices
Commit messages and changelogs
When you update a package, you can reuse the text you wrote in the .changes
file in the git commit message.
To do so, follow the standard format described here, which looks like this:
------------------------------------------------------------------- Sat Jan 11 16:37:07 UTC 2025 - Your Name <your@emailcom> - Update to new upstream release x.y.z: * bling and changes from upstream for that version * just the relevant parts, no info about other OS * and keep it as short as possible ------------------------------------------------------------------- Sat Jan 10 16:37:07 UTC 2025 - Your Name <your@emailcom> - Initial package of packagename 1.0 for openSUSE:
You have various ways to reuse your changelog.
Changelog alias
Use the following line:
git diff -U0 --cached *.changes | grep '^[+]' | grep -Ev '^(--- a/|\+\+\+ b/)' | tail -n +4 | cut -c4- | git commit -F -
Add it as an alias to your shell:
vi *.zshrc alias gitum="git diff -U0 --cached *.changes | grep '^[+]' | grep -Ev '^(--- a/|\+\+\+ b/)' | tail -n +4 | cut -c4- | git commit -F -"
After you add a file to be contained in the next commit with git add *.spec *.changes *.tar.gz
, you can now run gitum
to take the commit message from the staged changes file, remove the boilerplate, and commit.
insteadOf
If tired of writing src.opensuse.org
, you can use insteadOf
in your ~/.gitconfig file. Add this to the config:
[url "gitea@src.opensuse.org:"]
insteadOf = soo:
Now you can simply use git clone soo:user/repo
.
sha256 repos with Gitea client
Most of the time you actually donât want to create a new repository from scratch, but use prepared template, for that you could run
tea repo ct --name appropriateName --template pool/new_package
(yes, the name of the template is literally pool/new_package
).
If you actually really need to make a fresh blank repository, and because we require SHA256
repositories, you can run (from version 61.2.0 onwards):
tea repo create --name appropriateName --object-format sha256
Tool reference
A quick overview of tools that are used in this guide:
- git
- osc
- git-obs
- git-obs-hooks
- tea
- autogits: source of autogits_obs_staging_bot, autogits-devel bots