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.

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.

Command comparison
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 security:tls:staging libstrophe
osc co 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

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.

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.

Git hooks

Install git hooks from git-obs-hooks. A proposal regarding changes to files can be seen here.

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.

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

openSUSE:Git Packaging Workflow

Contents