diff --git a/.editorconfig b/.editorconfig index 32f4e1e1..fb10ef01 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,26 +1,9 @@ # -*- coding: utf-8 -*- -# # This file is part of Invenio. -# Copyright (C) 2016 CERN. -# -# Invenio is free software; you can redistribute it -# and/or modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of the -# License, or (at your option) any later version. -# -# Invenio is distributed in the hope that it will be -# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Invenio; if not, write to the -# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -# MA 02111-1307, USA. +# Copyright (C) 2025 CERN. # -# In applying this license, CERN does not -# waive the privileges and immunities granted to it by virtue of its status -# as an Intergovernmental Organization or submit itself to any jurisdiction. +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. root = true diff --git a/.travis.yml b/.travis.yml index ed1ed703..264d2f55 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,26 +1,9 @@ # -*- coding: utf-8 -*- -# # This file is part of Invenio. -# Copyright (C) 2016 CERN. -# -# Invenio is free software; you can redistribute it -# and/or modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of the -# License, or (at your option) any later version. -# -# Invenio is distributed in the hope that it will be -# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Invenio; if not, write to the -# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -# MA 02111-1307, USA. +# Copyright (C) 2025 CERN. # -# In applying this license, CERN does not -# waive the privileges and immunities granted to it by virtue of its status -# as an Intergovernmental Organization or submit itself to any jurisdiction. +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. notifications: diff --git a/AUTHORS.rst b/AUTHORS.rst index 60529a07..e3dd1992 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,26 +1,9 @@ .. This file is part of Invenio. - Copyright (C) 2016 CERN. - - Invenio is free software; you can redistribute it - and/or modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the - Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307, USA. - - In applying this license, CERN does not - waive the privileges and immunities granted to it by virtue of its status - as an Intergovernmental Organization or submit itself to any jurisdiction. + Copyright (C) 2025 CERN. + Invenio is free software; you can redistribute it and/or modify it + under the terms of the MIT License; see LICENSE file for more details. Authors ======= diff --git a/CHANGES.rst b/CHANGES.rst index 18c8819e..1f6caed1 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,27 +1,10 @@ .. This file is part of Invenio. - Copyright (C) 2016-2024 CERN. + Copyright (C) 2016-2025 CERN. Copyright (C) 2024-2025 Graz University of Technology. - Invenio is free software; you can redistribute it - and/or modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the - Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307, USA. - - In applying this license, CERN does not - waive the privileges and immunities granted to it by virtue of its status - as an Intergovernmental Organization or submit itself to any jurisdiction. - + Invenio is free software; you can redistribute it and/or modify it + under the terms of the MIT License; see LICENSE file for more details. Changes ======= diff --git a/MANIFEST.in b/MANIFEST.in index d699aee6..d65e9b13 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,26 +1,9 @@ # -*- coding: utf-8 -*- -# # This file is part of Invenio. -# Copyright (C) 2023 CERN. -# -# Invenio is free software; you can redistribute it -# and/or modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of the -# License, or (at your option) any later version. -# -# Invenio is distributed in the hope that it will be -# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Invenio; if not, write to the -# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -# MA 02111-1307, USA. +# Copyright (C) 2025 CERN. # -# In applying this license, CERN does not -# waive the privileges and immunities granted to it by virtue of its status -# as an Intergovernmental Organization or submit itself to any jurisdiction. +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. exclude .dockerignore diff --git a/README.rst b/README.rst index f993df5a..1509ae49 100644 --- a/README.rst +++ b/README.rst @@ -1,25 +1,9 @@ .. This file is part of Invenio. - Copyright (C) 2023 CERN. - - Invenio is free software; you can redistribute it - and/or modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of the - License, or (at your option) any later version. - - Invenio is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with Invenio; if not, write to the - Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307, USA. - - In applying this license, CERN does not - waive the privileges and immunities granted to it by virtue of its status - as an Intergovernmental Organization or submit itself to any jurisdiction. + Copyright (C) 2025 CERN. + + Invenio is free software; you can redistribute it and/or modify it + under the terms of the MIT License; see LICENSE file for more details. ================ Invenio-GitHub diff --git a/docs/api.rst b/docs/api.rst index 8bdd0d1c..5a5114b0 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -25,6 +25,5 @@ API Docs ======== -invenio_github --------------- - +.. automodule:: invenio_vcs.ext + :members: diff --git a/docs/conf.py b/docs/conf.py index 75c64ae5..c279174e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,27 +1,9 @@ # -*- coding: utf-8 -*- -# # This file is part of Invenio. -# Copyright (C) 2016 CERN. -# Copyright (C) 2023 Graz University of Technology. -# -# Invenio is free software; you can redistribute it -# and/or modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of the -# License, or (at your option) any later version. -# -# Invenio is distributed in the hope that it will be -# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Invenio; if not, write to the -# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -# MA 02111-1307, USA. +# Copyright (C) 2025 CERN. # -# In applying this license, CERN does not -# waive the privileges and immunities granted to it by virtue of its status -# as an Intergovernmental Organization or submit itself to any jurisdiction. +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. """Sphinx configuration.""" diff --git a/docs/contrib/github.rst b/docs/contrib/github.rst new file mode 100644 index 00000000..8f2fa15b --- /dev/null +++ b/docs/contrib/github.rst @@ -0,0 +1,41 @@ +.. + This file is part of Invenio. + Copyright (C) 2025 CERN. + + Invenio is free software; you can redistribute it and/or modify it + under the terms of the MIT License; see LICENSE file for more details. + +GitHub +====== + +To register GitHub as a VCS provider: + +* instantiate ``invenio_vcs.contrib.github.GitHubProviderFactory`` +* add it into the ``VCS_PROVIDERS`` list +* add it into the ``OAUTHCLIENT_REMOTE_APPS`` and ``OAUTHCLIENT_REST_REMOTE_APPS`` dictionaries under the same key as the ID (``github`` by default). +* configure ``GITHUB_APP_CREDENTIALS`` with your OAuth credentials generated by GitHub. + +For more details and a full example, please see `the Usage Guide <../usage>`_. + +================== +OAuth registration +================== + +To register a GitHub VCS provider, you need to `create an OAuth app `_ in your Developer Settings. + +You can enter any details for the app, but the authorization callback URL must be of the form: + +.. code-block:: + + https://example.com/oauth/authorized/github/ + +where ``example.com`` is the hostname of your instance and ``github`` is your configured provider ID. + +===================== +Special config values +===================== + +These optional values can be passed as keys of the ``config`` dictionary in the ``GitHubProviderFactory`` constructor. + +* ``shared_secret``: signing secret for the webhook payload. See the `GitHub documentation `_ for more details. Currently, one instance-wide secret is used for all webhooks. In addition, an internal per-repository access token is automatically attached to the webhook URL to validate access. +* ``insecure_ssl``: a boolean to indicate whether GitHub should accept self-signed or otherwise insecure SSl/TLS certificates when attempting to deliver the webhook. diff --git a/docs/contrib/gitlab.rst b/docs/contrib/gitlab.rst new file mode 100644 index 00000000..5ac9c47b --- /dev/null +++ b/docs/contrib/gitlab.rst @@ -0,0 +1,63 @@ +.. + This file is part of Invenio. + Copyright (C) 2025 CERN. + + Invenio is free software; you can redistribute it and/or modify it + under the terms of the MIT License; see LICENSE file for more details. + +GitLab +====== + +To register GitLab as a VCS provider: + +* instantiate ``invenio_vcs.contrib.gitlab.GitLabProviderFactory`` +* add it into the ``VCS_PROVIDERS`` list +* add it into the ``OAUTHCLIENT_REMOTE_APPS`` and ``OAUTHCLIENT_REST_REMOTE_APPS`` dictionaries under the same key as the ID (``gitlab`` by default). +* configure ``GITLAB_APP_CREDENTIALS`` with your OAuth credentials generated by GitLab. + +For more details and a full example, please see `the Usage Guide <../usage>`_. + +============= +Compatibility +============= + +The integration has been tested to work with the following versions of GitLab: + +* 18.x +* 17.x +* 16.x + +Support for anything but the latest major version is not guaranteed. +Please refer also to the `GitLab release policy `_. + +Any modified GitLab instances running custom code are also not guaranteed to be compatible. +You can, however, override the ``invenio_vcs.contrib.gitlab.GitLabProviderFactory`` and ``invenio_vcs.contrib.gitlab.GitLabProvider`` classes to add support for any non-standard API behaviour. + +================== +OAuth registration +================== + +To register a GitLab VCS provider, you need to `create a new Application `_ in your User Settings. +For a self-hosted GitLab instance, navigate to ``https://my-gitlab-instance.com/-/user_settings/applications``. + +Configure the app with the following settings: + +* You can use any name. +* Use a redirect URI of the form + + .. code-block:: + + https://example.com/oauth/authorized/gitlab/ + + where ``example.com`` is the hostname of your instance and ``gitlab`` is your configured provider ID. + +* Ensure 'Confidential' is checked. +* Select the ``api`` scope. Unfortunately, webhook management doesn't currently have a more narrow scope so this highly-general scope must be selected. + +===================== +Special config values +===================== + +These optional values can be passed as keys of the ``config`` dictionary in the ``GitHubProviderFactory`` constructor. + +* ``shared_validation_token``: Validation secret token for the webhook payload. See the `GitLab documentation `_ for more details. Currently, one instance-wide token is used for all webhooks. In addition, an internal per-repository access token is automatically attached to the webhook URL to validate access. diff --git a/docs/index.rst b/docs/index.rst index 2cdfd71e..edf5985e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,30 @@ Invenio-GitHub. usage +Provider Guides +--------------- + +These docs provide configuration instructions specific to each VCS provider. + +.. toctree:: + + contrib/github + contrib/gitlab + + + +Provider Guides +--------------- + +These docs provide configuration instructions specific to each VCS provider. + +.. toctree:: + + contrib/github + contrib/gitlab + + + API Reference ------------- diff --git a/docs/upgrading.rst b/docs/upgrading.rst new file mode 100644 index 00000000..a9b2d6ad --- /dev/null +++ b/docs/upgrading.rst @@ -0,0 +1,217 @@ +.. + This file is part of Invenio. + Copyright (C) 2025 CERN. + + Invenio is free software; you can redistribute it and/or modify it + under the terms of the MIT License; see LICENSE file for more details. + +Upgrading +========= + +====== +v4.0.0 +====== + +This version consists of a major refactor of the module and a full rename to ``invenio-vcs`` (from ``invenio-github``). +The new version has now been made generic and can support any VCS provider by implementing the relevant abstract classes. + +Contrib implementations are provided for GitHub and GitLab. +GitHub is supported with the exact same set of features as before, meaning this module can continue to be used for the original +purpose of ``invenio-github`` with just some migrations and configuration changes required. + +Please follow this guide if: + +- you are **not** using InvenioRDM; or +- you would like to try out ``invenio-vcs`` before InvenioRDM v14 is released. + + - This is not officially supported but should work for the most part. + +RDM-specific instructions can instead be found in the `InvenioRDM upgrade guide `_. + +-------------------------- +1. Update the dependencies +-------------------------- + +In your ``Pipfile`` (or any similar file you are using to manage dependencies), change the name and version of the ``invenio-vcs`` packages. +Additionally, you will need to ensure some other dependencies are up to date for compatibility with the new changes. + +.. code-block:: toml + + [packages] + # ... + invenio-vcs = ">=4.0.0,<5.0.0" + invenio-rdm-records = "TODO" + invenio-app-rdm = "TODO" + invenio-oauthclient = "TODO" + +.. note:: + + ``invenio-vcs`` is no longer packaged by default with InvenioRDM, as was the case with ``invenio-github``. + You must declare it as an explicit dependency on the instance level. + +Next, run the install operation and make sure the old module is no longer installed. +Having both installed simultaneously will lead to numerous conflicts, especially with Alembic migrations. + +.. code-block:: bash + + invenio-cli install + pip uninstall invenio-github + +---------------------------------- +2. Perform the database migrations +---------------------------------- + +Depending on the size of your instance, the migrations can be performed either automatically by running an Alembic script, or manually by +carefully following the instructions in this guide. + +If your instance meets one of these criteria, please use the manual method to avoid database stability issues: + +- An ``oauthclient_remoteaccount`` table with more than 50k rows +- A ``github_repositories`` table with more than 100k rows + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2a. Automated Alembic script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Run the upgrade command: + +.. code-block:: bash + + pipenv run invenio alembic upgrade + +^^^^^^^^^^^^^^^^^ +2b. Manual method +^^^^^^^^^^^^^^^^^ + +.. SQL auto-generated from migration file using `alembic upgrade --sql` + +In an SQL shell (e.g. ``psql`` for PostgreSQL), execute the following: + +.. code-block:: sql + + BEGIN; + CREATE TABLE vcs_repositories ( + id uuid NOT NULL, + provider_id character varying(255) NOT NULL, + name character varying(255) NOT NULL, + hook character varying(255), + enabled_by_user_id integer, + created timestamp without time zone NOT NULL, + updated timestamp without time zone NOT NULL, + provider character varying(255) DEFAULT 'github'::character varying NOT NULL, + default_branch character varying(255) DEFAULT 'master'::character varying NOT NULL, + description character varying(10000), + license_spdx character varying(255) + ); + ALTER TABLE ONLY vcs_repositories ADD CONSTRAINT pk_vcs_repositories PRIMARY KEY (id); + ALTER TABLE ONLY vcs_repositories ADD CONSTRAINT uq_vcs_repositories_provider_name UNIQUE (provider, name); + ALTER TABLE ONLY vcs_repositories ADD CONSTRAINT uq_vcs_repositories_provider_provider_id UNIQUE (provider, provider_id); + ALTER TABLE ONLY vcs_repositories ADD CONSTRAINT fk_vcs_repositories_enabled_by_user_id_accounts_user FOREIGN KEY (enabled_by_user_id) REFERENCES accounts_user(id); + + CREATE TABLE vcs_releases ( + id uuid NOT NULL, + provider_id character varying(255) NOT NULL, + tag character varying(255), + errors jsonb, + repository_id uuid, + event_id uuid, + record_id uuid, + status character(1) NOT NULL, + created timestamp without time zone NOT NULL, + updated timestamp without time zone NOT NULL, + provider character varying(255) DEFAULT 'github'::character varying NOT NULL + ); + ALTER TABLE ONLY vcs_releases ADD CONSTRAINT pk_vcs_releases PRIMARY KEY (id); + ALTER TABLE ONLY vcs_releases ADD CONSTRAINT uq_vcs_releases_provider_id_provider UNIQUE (provider_id, provider); + ALTER TABLE ONLY vcs_releases ADD CONSTRAINT uq_vcs_releases_provider_id_provider_tag UNIQUE (provider_id, provider, tag); + CREATE INDEX ix_vcs_releases_record_id ON vcs_releases USING btree (record_id); + ALTER TABLE ONLY vcs_releases ADD CONSTRAINT fk_vcs_releases_event_id_webhooks_events FOREIGN KEY (event_id) REFERENCES webhooks_events(id); + ALTER TABLE ONLY vcs_releases ADD CONSTRAINT fk_vcs_releases_repository_id_vcs_repositories FOREIGN KEY (repository_id) REFERENCES vcs_repositories(id); + COMMIT; + +Next, you must perform some manual data migrations: + +* The ``oauthclient_remoteaccount`` table stores the user's *entire* GitHub repository list as a dictionary within the ``extra_data`` column. + Before the upgrade, the format is as follows: + + .. code-block:: json + + { + "last_sync":"2025-10-15T12:30:01.027133+00:00", + "repos": { + "123": { + "id": "123", + "full_name": "org/repo", + "description": "An example repository", + "default_branch": "main" + } + } + } + + In the new format, we no longer store repos in this JSON column. This is an inefficient approach that systems with hundreds of thousands + of repos have outgrown. + Previously, only *activated* repos were stored in the ``github_repositories`` table. + Now, *all* repos are stored directly as rows of the ``vcs_repositories`` table. + Whether or not they're activated is indicated by the presence of non-null values for the ``hook`` and ``enabled_by_user_id`` columns. + + You must perform this migration, leaving only the ``"last_sync"`` value in the ``extra_data`` JSON column. + Not all columns of the ``vcs_repositories`` table need to be filled during the migration. + The following columns can be left blank and will be filled during the first sync after the migration: + + * ``description`` + * ``license_spdx`` + + The value for ``provider`` defaults to ``github``. + +* The ``github_repositories`` table needs to be copied over to the ``vcs_repositories`` table, taking into account the changed columns. + This should be merged with the new repos created by copying data from ``oauthclient_remoteaccount`` as shown above. + +* The ``github_releases`` table needs to be copied over to the ``vcs_releases`` table. + This can *not* be done automatically during a sync and needs to be done manually during the migration. + +You can use this script as a starting point to automating these changes, but it may need some customisation depending on the size +and uptime requirements of your instance. + +.. raw:: html + +
+ Example script + +This script is non-destructive and atomic and should work for the majority of use cases, but may need slight customisation. +You can set the database connection string via the ``UPGRADE_DB`` environment variable. + +.. code-block:: python + + +.. raw:: html + +
+ +Finally, once you are certain that all data has been copied over to the new tables, you can finish the migration +by running the following SQL commands: + +.. code-block:: sql + + BEGIN; + CREATE TABLE vcs_repository_users ( + repository_id UUID NOT NULL, + user_id INTEGER NOT NULL, + PRIMARY KEY (repository_id, user_id), + CONSTRAINT fk_vcs_repository_users_repository_id_vcs_repositories FOREIGN KEY(repository_id) REFERENCES vcs_repositories (id), + CONSTRAINT fk_vcs_repository_users_user_id_accounts_user FOREIGN KEY(user_id) REFERENCES accounts_user (id) + ); + DROP TABLE github_repositories; + DROP TABLE github_releases; + COMMIT; + +Mark the relevant migration as having been manually performed: + +.. code-block:: bash + + invenio alembic stamp invenio_github@1754318294 + +.. note:: + + The Alembic branch name ``invenio_github`` is unchanged despite all the other renamed references. + Changing the name of an Alembic branch is not supported and would introduce too many bugs to make it + worthwhile. diff --git a/docs/usage.rst b/docs/usage.rst index e8ebe1ac..de52ecb1 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -25,4 +25,114 @@ Usage ===== -.. automodule:: invenio_github +Invenio-VCS allows you to flexibly configure multiple VCS providers and allow users to sync their repositories. +These can then be published as records (in InvenioRDM) or any other customisable action can be performed when a release is made. + +Currently, the following VCS providers are officially supported in this module: + +* GitHub +* GitLab + +However, you can add support for any other provider (including non-Git ones) by implementing an abstract class. + +This guide explains how to configure this module in general, while the corresponding guides for each provider go into more detail about the specific steps required. + +=========== +Quick start +=========== + +1. Choose which provider you'd like to use. We'll use GitHub in this example. In ``invenio.cfg`` create the provider factory corresponding to your provider: + + .. code-block:: python + + _vcs_github = GitHubProviderFactory( + base_url="https://github.com", + webhook_receiver_url="https://example.com/api/hooks/receivers/github/events/?access_token={token}", + ) + + These are the only two required arguments, and they're the same for all providers. For more details, see :ref:`provider-arguments`. + + +2. Configure the OAuth client. Each provider provides its own configuration for ``invenio-oauthclient`` through which users can authenticate to get the necessary access token for syncing their repositories. + This should be added to any OAuth clients you may already have configured: + + .. code-block:: python + + OAUTHCLIENT_REMOTE_APPS = { + "github": _vcs_github.remote_config, + } + + OAUTHCLIENT_REST_REMOTE_APPS = { + "github": _vcs_github.remote_config, + } + + If you used a custom ``id`` when constructing the provider factory, this ID must correspond to that. The default ID for the GitHub provider is ``github``. + +3. Register an OAuth application with the provider. For GitHub, this can be done through the `Developer Settings `_. Please refer to the provider documentation for more details. + + Usually, you'll be asked for a redirect URL. By default, this will be of the form: + + .. code-block:: + + https://example.com/oauth/authorized/github/ + + where ``github`` corresponds to the ID of your provider factory. + + Once your app is registered, you'll be given a Client ID and Secret. You need to specify these to ``invenio-oauthclient``: + + .. code-block:: python + + GITHUB_APP_CREDENTIALS = { + "consumer_key": "your_client_id", + "consumer_secret": "your_client_secret", + } + + .. note:: + + The name of this config variable is specified by the ``credentials_key`` constructor argument of the provider factory. The '``GITHUB_``' is *not* derived from the ID, so you'll need to manually override this argument if you're using multiple instances of the same provider. + +4. Register the provider. By adding provider factories to this list, you can enable each of them as a repository syncing method. + + .. code-block:: python + + VCS_PROVIDERS = [_vcs_github] + + You can add multiple of the same type of provider here. For example, you could have both public GitHub.com and a self-hosted GitHub Enterprise instance. The only requirement is to use a different ID and ``credentials_key`` for each provider factory. + + .. caution:: + + Once repositories have been enabled from a given provider, removing it from this list is a dangerous operation. It's an unsupported behaviour that could cause unexpected errors and inconsistencies. + +.. _provider-arguments: + +================== +Provider arguments +================== + +When constructing the provider factory, there are some common arguments that can be configured: + +* ``base_url`` (**required**): the URL of the VCS instance, for example ``https://github.com``. This can correspond to either the public officially hosted instance or a self-hosted one. + +* ``webhook_receiver_url`` (**required**): the endpoint on your Invenio server that will handle webhook events from GitHub. This will almost always follow the pattern shown below, but can be customised depending on your use of ``invenio-webhooks``. The ``{token}`` variable can be placed anywhere in the URL and is used to validate the authenticity of the webhook call. + + .. code-block:: + + https://example.com/api/hooks/receivers/github/events/?access_token={token} + +* ``id``: uniquely identifies the provider within your instance. This value is used across database models and URLs to relate data to the provider. Once it has been used, the ID must not be changed. Each provider comes with a default ID (e.g. ``github``) but this should be changed if multiple instances of the same provider are being used. + +* ``name``: the displayed name of the provider, e.g. ``GitHub``. You can, for example, set this to an institution-specific name to make it clear to users that it's not referring to the public instance. + +* ``description``: a short text explaining the role of the provider in the instance. Shown in the user's OAuth settings page. + +* ``credentials_key``: the name of the config variable specifying the OAuth Client ID and Secret for ``invenio-oauthclient``. + +* ``config``: a dictionary of custom provider-specific configuration options. + +============= +Configuration +============= + +.. automodule:: invenio_vcs.config + :members: + :exclude-members: get_provider_by_id, get_provider_list diff --git a/invenio_vcs/config.py b/invenio_vcs/config.py new file mode 100644 index 00000000..86ca5b94 --- /dev/null +++ b/invenio_vcs/config.py @@ -0,0 +1,64 @@ +# -*- coding: utf-8 -*- +# This file is part of Invenio. +# Copyright (C) 2025 CERN. +# +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. + +"""You can use these options to configure the Invenio-VCS module. + +Other than ``VCS_PROVIDERS``, they are all optional and configured with reasonable defaults. +""" + +from typing import TYPE_CHECKING + +from flask import current_app + +if TYPE_CHECKING: + from invenio_vcs.providers import RepositoryServiceProviderFactory + +VCS_PROVIDERS = [] +"""The list of RepositoryProviderFactory instances. + +These will be visible to the user in their settings and they will be able to sync repositories +from all of them. Multiple instances of different providers as well as of the same provider +can be combined in this list, but each provider must have a unique ``id`` and ``credentials_key``. +""" + +VCS_RELEASE_CLASS = "invenio_vcs.service:VCSRelease" +"""VCSRelease class to be used for release handling.""" + +VCS_TEMPLATE_INDEX = "invenio_vcs/settings/index.html" +"""Repositories list template.""" + +VCS_TEMPLATE_VIEW = "invenio_vcs/settings/view.html" +"""Repository detail view template.""" + +VCS_ERROR_HANDLERS = None +"""Definition of the way specific exceptions are handled.""" + +VCS_MAX_CONTRIBUTORS_NUMBER = 30 +"""Max number of contributors of a release to be retrieved from vcs.""" + +VCS_CITATION_FILE = None +"""Citation file name.""" + +VCS_CITATION_METADATA_SCHEMA = None +"""Citation metadata schema.""" + +VCS_ZIPBALL_TIMEOUT = 300 +"""Timeout for the zipball download, in seconds.""" + + +def get_provider_list(app=current_app) -> list["RepositoryServiceProviderFactory"]: + """Get a list of configured VCS provider factories.""" + return app.config["VCS_PROVIDERS"] + + +def get_provider_by_id(id: str) -> "RepositoryServiceProviderFactory": + """Get a specific VCS provider by its registered ID.""" + providers = get_provider_list() + for provider in providers: + if id == provider.id: + return provider + raise Exception(f"VCS provider with ID {id} not registered") diff --git a/requirements-devel.txt b/requirements-devel.txt index 58f6e0db..702b0ae9 100644 --- a/requirements-devel.txt +++ b/requirements-devel.txt @@ -1,23 +1,6 @@ # -*- coding: utf-8 -*- -# # This file is part of Invenio. -# Copyright (C) 2016 CERN. -# -# Invenio is free software; you can redistribute it -# and/or modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of the -# License, or (at your option) any later version. -# -# Invenio is distributed in the hope that it will be -# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Invenio; if not, write to the -# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -# MA 02111-1307, USA. +# Copyright (C) 2025 CERN. # -# In applying this license, CERN does not -# waive the privileges and immunities granted to it by virtue of its status -# as an Intergovernmental Organization or submit itself to any jurisdiction. +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. diff --git a/setup.cfg b/setup.cfg index d51fba95..2450b8ba 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,27 +1,10 @@ # -*- coding: utf-8 -*- -# # This file is part of Invenio. -# Copyright (C) 2023-2025 CERN. +# Copyright (C) 2025 CERN. # Copyright (C) 2023-2025 Graz University of Technology. # -# Invenio is free software; you can redistribute it -# and/or modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of the -# License, or (at your option) any later version. -# -# Invenio is distributed in the hope that it will be -# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Invenio; if not, write to the -# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -# MA 02111-1307, USA. -# -# In applying this license, CERN does not -# waive the privileges and immunities granted to it by virtue of its status -# as an Intergovernmental Organization or submit itself to any jurisdiction. +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. [metadata] name = invenio-github diff --git a/setup.py b/setup.py index 2b4d4968..b3053b2d 100644 --- a/setup.py +++ b/setup.py @@ -1,27 +1,10 @@ # -*- coding: utf-8 -*- -# # This file is part of Invenio. -# Copyright (C) 2023 CERN. -# Copyright (C) 2023 Graz University of Technology. -# -# Invenio is free software; you can redistribute it -# and/or modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of the -# License, or (at your option) any later version. -# -# Invenio is distributed in the hope that it will be -# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Invenio; if not, write to the -# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, -# MA 02111-1307, USA. +# Copyright (C) 2025 CERN. +# Copyright (C) 2023-2025 Graz University of Technology. # -# In applying this license, CERN does not -# waive the privileges and immunities granted to it by virtue of its status -# as an Intergovernmental Organization or submit itself to any jurisdiction. +# Invenio is free software; you can redistribute it and/or modify it +# under the terms of the MIT License; see LICENSE file for more details. """Invenio module that adds GitHub integration to the platform."""