Skip to content

Commit

Permalink
Update scmsync documentation
Browse files Browse the repository at this point in the history 
changed defaults and changed recommendations
  • Loading branch information
@adrianschroeter
adrianschroeter committed Mar 8, 2024
1 parent b9ee25f commit e817636
Showing 1 changed file with 43 additions and 22 deletions.
65 changes: 43 additions & 22 deletions xml/obs_scm_bridge.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,31 +12,35 @@
xmlns:ns5="http://www.w3.org/2000/svg"
xmlns:ns4="http://www.w3.org/1999/xhtml"
xmlns:ns="http://docbook.org/ns/docbook">
<title>SCM Bridge [EXPERIMENTAL]</title>
<title>SCM Bridge</title>

<sect1 xml:id="sec.obs.obs_scm_bridge">
<title>SCM Bridge</title>

<sect2 xml:id="sec.obs.obs_scm_bridge.setup.introduction">
<title>Introduction</title>

<para>The SCM bridge allows to setup single packages or entire projects in any trusted SCM repositories.
<para>The SCM bridge allows to setup single package or entire project sources to be stored and
maintained in any trusted SCM repositories.
However, the only supported SCM is currently git.</para>

<para>This allows to manage the entire package sources in an external SCM repository. While the classic
OBS services for scms (like obs_scm or tar_scm) are using the workflows inside of OBS, these workflows
have to happen inside of the SCM provider instance. OBS will just verify the authenticity of that resource in
future.</para>
<para>This allows to run the entire packaging source update in an external SCM repository using the
native tooling. It is recommended to have this SCM server on the same trust level as the OBS
instance. However, any SCM server reachable via network could be used.</para>

<para>osc can be used to checkout sources. This will create a scm repository, so any modification needs to be
<para>osc can still be used to checkout sources. This will create a scm repository, so any modification needs to be
done using the native scm tooling (eg. git). osc can still be used for local building and checking server
side build results.</para>

<para>Be aware that any source mechanics like link or branch of OBS are not working when using the bridging.
This means also that workflows are not working anymore or are limited. For example a submit request would
<para>Be aware that any source modifican mechanics submit requests or link behaviour may not work
differently or not all. For example you can not use automatic package source merging via _link files anymore.
This means also that workflows inside of OBS are not working anymore or are limited. For example a submit request would
still work when having scmsync on package level, but the user would manually specify the target always.
It won't work at all when the entire project is managed via git. This briding mechanic is designed to follow
the configured git provider, so this instance need to provide any required workflow.</para>

<para>Furthermore it is recommended to configure a global notification hook in the SCM server to
allow OBS to follow the sources automatically.</para>
</sect2>

<sect2 xml:id="sec.obs.obs_scm_bridge.setup.package">
Expand All @@ -46,13 +50,20 @@

<screen>&lt;scmsync&gt;https://gitlab.com/some/repository&lt;/scmsync&gt;</screen>

<para>The repository is cloned including all subdirectories, but the build descriptions need to be
available on top level.</para>
<para>The repository is cloned including all subdirectories and submodules.
However the build descriptions need to be available on top level.</para>

<para>Large binary files may be store using git LFS or by referencing external build assets,
using asset management. These assets will get downloaded and verified as well. The advantage is
that this information can also be using to build SBOM informations. Have a look in
<link xlink:href="http://opensuse.github.io/obs-build/pbuild.html#_remote_assets">the pbuild
documentation</link> for further details on this. </para>

<para>It is recommended just to reference further external build assets, like tar balls or git repositories
using asset management. These assets will get downloaded and verified as well. Have a look in
<link xlink:href="http://opensuse.github.io/obs-build/pbuild.html#_remote_assets">the pbuild
documentation</link> for further details on this. </para>
<para>Another typical scenario is to have an own git repository owned by the package maintainer where
a build descriptions and distribution specific files are store. The sources from the upstream
project may be added via a git submodule. However, for many build types like rpm builds it is recommended
to build a tar ball at buildtime for the source rpm. This can be achieved with buildtime source services.
</para>
</sect2>

<sect2 xml:id="sec.obs.obs_scm_bridge.setup.project">
Expand All @@ -61,18 +72,17 @@
<para>An entire project can be setup by defining the scmsync tag in project meta data. Every top level
subdirectory of the scm repository is considered as a package.</para>

<para>Large projects can use git submodules for each package. This avoids the need to
<para>Large projects may use git submodules for each package. This avoids the need to
clone the entire project for modifications on single packages.</para>

<para>The build configuration part can get stored as '_config' file in the top level directory.</para>

</sect2>

<sect2 xml:id="sec.obs.obs_scm_bridge.implementation_and_limitations">
<title>Implementation and Limitations</title>

<para>The sources are currently cloned for the OBS source server to allow OBS to process them. This
is to be considered as an internal implementation detail and may change in future.</para>
is to be considered as an internal implementation detail and may change in future.</para>
<para>
<itemizedlist>
<listitem>
Expand All @@ -82,15 +92,15 @@
<para>Git VCS history: is not included for server side builds by default to save storage space. It can be included by adding a keepmeta=1 CGI parameter to the URL. This is not needed for local building when using osc.</para>
</listitem>
<listitem>
<para>Git LFS files: are not included by default. They can be included by adding a lfs=1 CGI parameter to the URL.</para>
<para>Git LFS files: are included by default. They can be excluded by adding a lfs=0 CGI parameter to the URL.</para>
</listitem>
<listitem>
<para>Using just a sub directory of the git repository can be done by adding a subdir=DIRECTORY CGI parameter to the URL.</para>
</listitem>
<listitem>
<para>Architecture specific remote assets can be selected by adding a arch=ARCH CGI parameter to the URL.</para>
</listitem>
</itemizedlist>
</itemizedlist>
As example, this would like this for the subdirectory case:
<screen>&lt;scmsync&gt;https://gitlab.com/some/repository?subdir=MY_SUBDIRECTORY&lt;/scmsync&gt;</screen>
</para>
Expand All @@ -105,7 +115,8 @@
branches for implementing CI workflows. For example a submission test building just a subset, a clean build
and a final reviewed build.
</para>
</sect3>
</sect3>

<sect3 xml:id="sec.obs.obs_scm_bridge.setup.specials.pbuild">
<title>Converting to a project git</title>
<para>A project git repository is mostly the same as any project for the pbuild tool. The
Expand All @@ -115,6 +126,16 @@
honored by OBS, but it can be part of the git tree anyway for pbuild users.
</para>
</sect3>

<sect3 xml:id="sec.obs.obs_scm_bridge.setup.specials.fork">
<title>Forking a scmsync package</title>
<para>The obs server allows to create a cloned project with another package using a specified
scm repository. This can be used by tooling to create forked test builds for merge requests.
The api POST route for this is
<screen>/source/PROJECT/PACKAGE?cmd=fork&amp;scmsync=NEW_SCM_URL</screen>
<!-- osc will provide functionality to create a git fork and an OBS package fork afterwards -->
</para>
</sect3>
</sect2>

<sect2 xml:id="sec.obs.obs_scm_bridge.update_notifications">
Expand All @@ -127,7 +148,7 @@
by referencing it via the scmsync meta tag.
</para>
<para>
This has been only implemented for gitea atm, you can find details in the <link xlink:href="https://github.com/adrianschroeter/obs-gitea-bridge">obs-gitea-bridge</link> documentation.
This has been only implemented for gitea atm, you can find details in the <link xlink:href="https://github.com/openSUSE/obs-gitea-bridge">obs-gitea-bridge</link> documentation.
</para>
</sect2>
</sect1>
Expand Down

0 comments on commit e817636

Please sign in to comment.