Open Build Service Connector
Visual Studio Code extension for integration with the Open Build
Service: it allows you to view existing packages
and projects, check them out locally, build them and integrates into VSCode's
source control.
NOTE: The extension is still in the Beta, thus exercise caution when using
it in production.
Features
Be sure to checkout the unveiling talk at SUSECON Digital
2020 (session id DEV-1287) and the
presentation from the openSUSE + LibreOffice Virtual Conference
2020. Both
presentations include a live demo in the second half.
Bookmark and view projects
You can bookmark projects from OBS so that they are directly accessible from
within VSCode by clicking on the Bookmark a Project entry in the BOKMARKED PROJECTS view:
The interactive guide will prompt you for the name of the project and for the
packages that should be bookmarked:
You can browse the bookmarked projects, packages and their files. Clicking on a
file opens a read-only view of the file contents retrieved from the Open Build
Service:
Checking out projects and packages
Packages (or whole projects) have to be checked locally out so that
modifications can be send back to the Open Build Service. They can be checked
out by clicking on the repo-clone icon on a Package or Project entry in the
Bookmarked Projects view or on the icon the upper right if a file from a package
is currently open:
Packages or Projects that are not bookmarked can be checked out by invoking the
command "Check out the project" or "Check out the package" command:
Repository and Current Project view
The "Repositories" view shows the repositories of the project to which the
currently opened file belongs to. Similarly the "Current Project" view shows the
project to which the package belongs to:
New repositories can be added to a project by using clicking on the + in the
bar of the "Repositories" view:
Each repository can be expanded by clicking on it which reveals the paths and
architectures of the specific repository. Paths and architectures can be added
or removed via the + and - icons that appear next to the respective entries
in the tree view:
Repository paths can be modified in the same way, additionally the individual
paths can be moved up and down:
Source control integration
Locally checked out packages are integrated into VSCode's source control and
provide the basic features:
- the fringe indicates whether lines were changed
- clicking on the fringe opens a
QuickDiff view
- individual changes or all changes in a file can be reverted by clicking on the
"discard" icon
- clicking on a modified file in the Source control menu opens a full diff of
the respective file
- the "Package History" view shows the past commits of the current package
The modifications can be committed to the Open Build Service via the source
control input box. Optionally one can use the same input box to add an entry to
the changelog:
Build locally checked out packages
If osc is available in $PATH, then the
extension provides VSCode with tasks to build a locally checked out package:
Branch packages and submit changes back
Bookmarked packages can be branched into your home project from the context
menu:
The branched package will be directly bookmarked and checked out to a desired
location on your filesystem. Once you have applied your changes, you can submit
the changes back via a submitrequest:
Accounts
The extension provides two buttons in the Bookmarked Projects section if no
accounts are saved:
The upper button launches an interactive wizard to import an account into the
extension, the lower one imports accounts from your ~/.config/osc/oscrc or
~/.oscrc into the extension. The accounts are stored in your setings.json
and can be modified via that file. For convenience, the extension provides the
option to open settings.json at the correct position via an entry in the
server's context menu:
For further details concerning the account settings, please refer to the
Extension Settings section.
SSL Certificates
If your instance of the Open Build Service uses a custom SSL certificate that is
not stored in Visual Studio Code's certificate storage, then you will have to
add the CA certificate to extension. The most convenient way is via the
interactive account import wizard, which can be launched via the command Add an existing account from the Open Build Service to the extension. It will check
whether it can establish a secure connection and if not prompt you to either
provide the CA certificate file yourself or it can automatically import it for
you. Beware that in the later case, you must verify that the extension
downloaded the correct certificate (it will present you with the fingerprint of
the certificate during the import process).
Build status and build log
You can query the current build status for all repositories and architectures as
well as the build log via the commands Show the build status and Show the build log. These are available as stand alone commands or via the context menu
of bookmarked packages:
The build status is presented as a virtual text document with an entry for each
repository and each architecture containing the published binaries and
information about these:
The individual repositories and architectures can be folded via the twistie in
the gutter.
The build log of a package is fetched from the Open Build Service and shown as a
read only document. You will first be queried for the repository and
architecture for which you want to view the log, before it is displayed. In case
the build is currently running, then the log will be updated live inside VSCode.
Requirements
You need an account on an instance of the Open Build Service
(e.g. https://build.opensuse.org/) to use this extension. If you don't have one,
you can sign up for an account on https://build.opensuse.org/
here.
Extension Settings
accounts
Your account(s) are stored in the settings.json as follows:
"vscode-obs.accounts": [
{
"accountName": "Alias for this account",
"apiUrl": "http://api.foo.com",
"username": "myUserName",
"realname": "YourRealName",
"email": "your_email@provider.tld",
"serverCaCertificate": "Paste a custom cert.pem in here if required"
},
{
// another account here
}
]
The only mandatory settings are accountName, apiUrl and username. Note
that the apiUrl is the url to the API of the Open Build Service instance,
which is not the same as the url to the web UI. For example on OBS the web UI is
accessible via build.opensuse.org, the API on the
other hand via api.opensuse.org.
Adding a realname and email is required to be able to add changelog entries,
but if you will not use that feature, then you needn't provide them. You can
also add a custom certificate to an account in case the specific instance uses a
certificate that is not in VSCode's certificate chain.
checkUnimportedAccounts
The extension will check on launch whether there are accounts in your
~/.config/osc/oscrc that have not been imported already. You can disable this
check by setting this value to false.
logLevel
Defines the log level that will be used. For most users error is a sensible
default as it will keep the size of the logfiles small. When submitting bug
reports, please set the loglevel to trace to receive a more complete log.
forceHttps
The extension will by default reject accounts that use http for
communication. If your instance cannot use https, then you can set forceHttps
to false to permit http connections. Caution: your account password will be
transmitted in clear text then! Use this only for connections that are protected
by other means as well (e.g. local only or a VPN).
Installation and setup
Secret storage
Linux users have to install
libsecret for storing the account
passwords. The installation command will differ depending on your distribution:
- on openSUSE:
sudo zypper in libsecret
- on Debian and Ubuntu:
sudo apt-get install libsecret-1-dev
- on Fedora, RHEL and CentOS:
sudo dnf install libsecret
- on Arch Linux:
sudo pacman -S libsecret
Next install the Open Build Service Connector from the Visual Studio Code
Marketplace / the Extension menu.
Once the extension is installed, you need to configure your account(s). The
extension will automatically prompt you to import any accounts from your
~/.config/osc/oscrc in case you are already using
osc. Otherwise you can add your account
either to your settings.json or by invoking the command Add an existing account from the Open Build Service to the extension which will guide you via
an interactive wizard. Once setup, you can always modify the general account
settings in your settings.json and change the account password via the command
Set the password of a Build Service Account.
MacOSX and Windows users don't have to install anything, as
node-keytar uses the operating system's
secret storage.
Building packages
The extension allows you to build checked out packages via
osc. To use this feature, please install osc
either using your distribution's package manager, from
OBS or from the
git repository.
Current limitations
Please also be sure to checkout the issue tracker!
Reporting Bugs
If you encounter a bug, please execute the command Open Error Reporting Page
and include the information presented in the opened document.
Credits
