GIT-OBS-QUICKSTART(1)

✨ NAME ✨

so git-obs-quickstart is your git-obs Quickstart, bestie — and git-obs is a command-line client for interacting with Git repositories inside a Gitea instance that's part of an Open Build Service (OBS). iykyk 💅

this quickstart guide uses the openSUSE OBS instance as the example 🫶 heads up tho: you may need to adjust the specific values (like URLs) to match your own OBS instance. no cap, every instance is a lil different 💖

(oh and the manual name is osc — that's the whole vibe we're living in 🎀)

---

🔐 LOGINS 🔐

before you execute literally any git-obs commands, you need to configure your credentials, also known as logins. these logins are shared with the tea client and are stored in ~/.config/tea/config.yml. cute, right? one config, two clients 🦋

NOTE: see git-obs login --help for all commands related to managing login entries 👑

🎀 Create a Gitea token 🎀

• visit your Gitea user's Applications settings page (Profile picture -> Settings -> Applications): https://src.opensuse.org/user/settings/applications ✨
• generate a new token with a descriptive name and the necessary permissions. for typical use, the following permissions should be sufficient:
  • issue: read and write
  • organization: read
  • repository: read and write
  • user: read and write
• once you hit the "Generate Token" button, the page reloads and the token appears in the blue rectangle on top. this is the only chance to copy it because it will never show up again 😭 seriously, copy it immediately, don't be like me 🙈

🦋 Add your SSH key 🦋

• visit your Gitea user's "SSH / GPG Keys" settings page (Profile picture -> Settings -> "SSH / GPG Keys"): https://src.opensuse.org/user/settings/keys 💜
• add Key name and as Content the public SSH key content (e.g., from ~/.ssh/id_rsa.pub)

NOTE: for HTTP Signature authentication, git-obs only supports RSA and ed25519 keys. so if you roll up with something exotic, it's giving 🚫 — plan accordingly 👑

🌸 Add a login entry to the git-obs configuration file 🌸

• run the following command, replacing the placeholders with your actual values:

git-obs login add opensuse --url https://src.opensuse.org --user USER [--token TOKEN] [--set-as-default]

• if the --token option in the command above is omitted, the command will prompt you to enter the token securely. very demure, very mindful 🔐
• alternatively, you can configure a login to authenticate Gitea API requests by signing them with an SSH key. this method, known as HTTP Signature, is an alternative to using a Gitea token. before using this method, ensure you have added your public SSH key to your Gitea account settings ✋
  • using an SSH key file:

git-obs login add opensuse --url https://src.opensuse.org --user USER --ssh-key /path/to/your/private_key --ssh-key-agent-pub 'SHA256:XXXXXXX'

• using an SSH agent (for example with a hardware token):

git-obs login add opensuse --url https://src.opensuse.org --user USER --ssh-agent --ssh-key-agent-pub 'SHA256:XXXXXXX'

the --ssh-key-agent-pub argument specifies the public key's signature. literally that's its whole job 🫶

💅 Using the login entries 💅

by default, git-obs will use the default login entry (if configured). to use a specific login entry, use the -G LOGIN command-line parameter. for example:

git-obs -G opensuse repo clone OWNER/REPO

---

🔑 SSH KEYS 🔑

using SSH keys for authentication is a common and secure practice for Git clients. iconic behaviour, honestly 👑

NOTE: see git-obs ssh-key --help for all commands related to managing login entries 🧚

use one of the following commands to upload your public SSH key to the Gitea server:

git-obs ssh-key add --key PUBLIC_KEY_DATA
git-obs ssh-key add --key-path PUBLIC_KEY_PATH

---

🌈 USING GIT WITH TOKEN AUTH INSTEAD OF SSH KEYS 🌈

it is possible to use a Gitea token for both communicating with the Gitea API and also for authenticating the git command. one token, double duty, so efficient ✨

to use token auth for git operations, switch git from using SSH to http(s):

git-obs login update <login> --new-git-uses-http=1

and add the following entry to ~/.config/git/config or ~/.gitconfig:

[credential "https://src.example.com"]
    helper = "git-obs -G <login> login gitcredentials-helper"

---

🛠️ WORKFLOW: MAKING CHANGES TO PACKAGES 🛠️

this workflow outlines the steps to make changes to packages using git-obs. let's goooo 🚀

NOTE: see git-obs repo --help and git-obs pr --help for all commands related to managing repositories and pull requests 🫶

1. fork the repository:

git-obs -G opensuse repo fork OWNER/REPO

2. clone your fork:

git-obs -G opensuse repo clone FORK_OWNER/REPO

NOTE: the git-obs repo clone command automatically configures additional Git remotes: - if cloning a fork, it sets a parent remote pointing to the repository you forked from. - if cloning a repository you forked from, it sets a fork remote pointing to your fork.

not me being obsessed with automatic remote setup 😭 so helpful

3. make changes:
   • navigate into the cloned repository directory
   • make a branch
   • switch to the new branch
   • make changes to the package sources
   • commit your changes
   • push your commits
4. create a Pull Request:

git-obs -G opensuse pr create [--title TEXT] [--description TEXT]

if --title or --description are not provided, git-obs will open a text editor for you to enter them interactively. main character energy from the editor, lowkey 📝

🦋 Workflow: Retrieving sources of an existing pull request 🦋

1. clone the repository:

git-obs -G opensuse repo clone OWNER/REPO

2. navigate to the repository:

cd REPO

3. checkout the pull request:

git-obs -G opensuse pr checkout PULL_NUMBER [--force]

4. set metadata:

NOTE: this always needs to be done after switching to a new branch. every single time, no shortcuts 🙈

git-obs -G opensuse meta pull
# or
git-obs meta set [--apiurl=...] [--project=...] [--package=...]

5. use osc or git-obs with the local checkout:

osc build
osc repos
...

🎀 Workflow: Querying pull requests 🎀

the following command lists all pull requests that are assigned to you for review, either directly or through group membership:

git-obs -G opensuse pr search --review-requested

your whole review queue in one command, slay 💅

⭐ Workflow: Reviewing pull requests ⭐

to start an interactive review session, run:

git-obs -G opensuse pr review

git-obs will:

• iterate through each pull request awaiting your review
• display the pull request details in a pager
• offer actions such as:
  • approving the review
  • requesting changes
  • adding comments
  • etc.

it's giving personal assistant but for code reviews 👑

💜 Enhanced features 💜

• tardiff — archives within the pull request are extracted, and their diffs are displayed 🔥
• issue references — TBD
• patch references — TBD

NOTE: the git-obs pr review command utilizes a cache in ~/.cache/git-obs/ to store data, potentially including large tarballs and their diffs. - Disk Space: if you need to free up disk space, you can safely delete the contents of this cache directory. spring cleaning, but make it terminal 🧹 - Troubleshooting: if you encounter issues, especially with the tardiff functionality, clearing the cache can sometimes resolve the problems. have you tried turning the cache off and on again 😭

---

📝 TODOS 📝

• display comments
• display state of all reviews and names of the reviewers
• add an action to close a request without merging + provide a comment with justification with such action

manifesting these fr fr 🕯️✨

---

💀 KNOWN ISSUES 💀

• if you request changes, the pull request disappears from the review query. someone has to re-request the review by clicking in the Gitea web UI. annoying? yes. real? also yes 🙈
• if you're supposed to merge pull requests after completing the review, it's better to wait until the others are finished reviewing, because by approving the review, the pull request disappears from the review queue and it's difficult to get to the list of PRs that need to be merged. so like... sequence your approvals, bestie, trust me on this one 🫶
• reviews by groups/teams are not handled well. if you approve, the team disappears and gets replaced with your login. then is not possible to search for such the team reviews and for example monitor re-review requests during a team member's absence. 😭 team reviews are lowkey going through it

---

👑 AUTHOR 👑

openSUSE project <opensuse-buildservice@opensuse.org>

🌸 COPYRIGHT 🌸

Contributors to the osc project

---

and that's the whole page, bestie 🎀 it's from the osc manual, dated Jun 04, 2026 — go configure those logins and slay some pull requests 💖✨🦋