mirror of
https://github.com/openSUSE/osc.git
synced 2026-02-22 03:35:29 +01:00
cbf98966b7
This change introduces support for authenticating against the Gitea API using an SSH agent. This provides a more secure and convenient alternative to storing private keys or API tokens directly in the configuration file. Key changes include: - A new HttpSigner class that can sign HTTP requests using either a local private key or a key from an SSH agent. - The osc git-obs login add and login update commands now accept --ssh-agent and --ssh-key-agent-pub arguments to configure SSH agent-based authentication. - The paramiko library is now used for SSH agent communication. It is an optional dependency and only required when using the SSH agent feature. - The Gitea API connection logic is updated to use the HttpSigner when SSH authentication is configured. This improves user experience by allowing them to leverage their existing SSH agent setup for Gitea authentication, avoiding the need to handle sensitive credentials manually.
261 lines
8.1 KiB
ReStructuredText
261 lines
8.1 KiB
ReStructuredText
==================
|
|
git-obs Quickstart
|
|
==================
|
|
|
|
``git-obs`` is a command-line client for interacting with Git repositories
|
|
within a Gitea instance that is part of an Open Build Service (OBS).
|
|
|
|
This quickstart guide uses the openSUSE OBS instance as an example.
|
|
You may need to adjust the specific values (like URLs) to match your own OBS instance.
|
|
|
|
|
|
Logins
|
|
======
|
|
|
|
Before executing 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``.
|
|
|
|
.. 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 <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.
|
|
|
|
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 <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.
|
|
|
|
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.
|
|
|
|
- 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.
|
|
|
|
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.
|
|
|
|
.. 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 Gitea token for both communicating with the Gitea API
|
|
and also for authenticating the git command.
|
|
|
|
|
|
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``.
|
|
|
|
.. 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:**
|
|
|
|
.. code::
|
|
|
|
git-obs -G opensuse repo fork OWNER/REPO
|
|
|
|
2. **Clone your fork:**
|
|
|
|
.. code::
|
|
|
|
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.
|
|
|
|
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:**
|
|
|
|
.. code::
|
|
|
|
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.
|
|
|
|
|
|
Workflow: Retrieving sources of an existing pull request
|
|
--------------------------------------------------------
|
|
|
|
1. **Clone the repository:**
|
|
|
|
.. code::
|
|
|
|
git-obs -G opensuse repo clone OWNER/REPO
|
|
|
|
|
|
2. **Navigate to the repository:**
|
|
|
|
.. code::
|
|
|
|
cd REPO
|
|
|
|
3. **Checkout the pull request:**
|
|
|
|
.. code::
|
|
|
|
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.
|
|
|
|
.. code::
|
|
|
|
git-obs -G opensuse meta pull
|
|
# or
|
|
git-obs meta set [--apiurl=...] [--project=...] [--package=...]
|
|
|
|
|
|
5. **Use osc or git-obs with the local checkout**
|
|
|
|
.. code::
|
|
|
|
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
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
- **Troubleshooting:** If you encounter issues, especially with the **tardiff** functionality, clearing the cache can sometimes resolve the problems.
|
|
|
|
|
|
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
|
|
|
|
|
|
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.
|
|
- 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.
|
|
- 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. |