From December 8 to December 10 the underlying cloud platform running GitLab CI jobs is being extended and thus, is unavailable. We do our best to compensate this with other resources but it might happen that you experience extended startup times for your CI jobs. Thanks for your understanding!

GitLab 14.5 is now available. 🚀 Learn what's new.

Verified Commit 61d8328d authored by Huste, Tobias (FWCC) - 111645's avatar Huste, Tobias (FWCC) - 111645
Browse files

global: add documentation

parent f8b36a82
Pipeline #9046 passed with stages
in 4 minutes and 58 seconds
......@@ -36,7 +36,7 @@ Module for Invenio that adds GitLab integration.
*This is an experimental developer preview release.*
TODO: Please provide feature overview of module
- OAuthClient configuration for Single-Sign-On via GitLab
- Automatic preservation of releases from one GitLab instance at a time
Further documentation is available on
https://data-management.pages.hzdr.de/invenio-gitlab
Further documentation is available on TODO.
......@@ -23,3 +23,63 @@ API Docs
.. automodule:: invenio_gitlab.ext
:members:
Database Models
---------------
.. automodule:: invenio_gitlab.models
:members:
Views
-----
Settings views
^^^^^^^^^^^^^^
.. automodule:: invenio_gitlab.views.gitlab
:members:
Badge views
^^^^^^^^^^^
.. automodule:: invenio_gitlab.views.badge
:members:
Celery Tasks
------------
.. automodule:: invenio_gitlab.tasks
:members:
.. autotask:: invenio_gitlab.tasks.process_release
.. autotask:: invenio_gitlab.tasks.disconnect_gitlab
Errors
------
.. automodule:: invenio_gitlab.errors
:members:
Handlers
--------
.. automodule:: invenio_gitlab.handlers
:members:
Receivers
---------
.. automodule:: invenio_gitlab.receivers
:members:
Utils
-----
.. automodule:: invenio_gitlab.utils
:members:
Bundles
-------
.. automodule:: invenio_gitlab.bundles
:members:
......@@ -24,6 +24,7 @@ from __future__ import print_function
import os
import sphinx.environment
import sphinx_rtd_theme
# -- General configuration ------------------------------------------------
......@@ -37,6 +38,7 @@ suppress_warnings = ['image.nonlocal_uri']
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'celery.contrib.sphinx',
'sphinx.ext.autodoc',
'sphinx.ext.coverage',
'sphinx.ext.doctest',
......@@ -126,15 +128,7 @@ todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
html_theme = 'alabaster'
html_theme_options = {
'description': 'Module for Invenio that adds GitLab integration.',
'show_powered_by': False,
'extra_nav_links': {
'invenio-gitlab@GitLab': 'https://gitlab.hzdr.de/rodare/invenio-gitlab',
}
}
html_theme = 'sphinx_rtd_theme'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
......@@ -145,7 +139,7 @@ html_theme_options = {
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
......@@ -324,8 +318,7 @@ texinfo_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
'python': ('https://docs.python.org/', None),
# TODO: Configure external documentation references, eg:
# 'Flask-Admin': ('https://flask-admin.readthedocs.io/en/latest/', None),
'SQLAlchemy': ('https://docs.sqlalchemy.org/en/latest/', None),
}
# Autodoc configuraton.
......
......@@ -16,9 +16,10 @@
You should have received a copy of the GNU General Public License
along with Rodare. If not, see <http://www.gnu.org/licenses/>.
.. _configuration-label:
Configuration
=============
Configuration Parameters
========================
.. automodule:: invenio_gitlab.config
:members:
......@@ -29,8 +29,8 @@ Invenio-GitLab.
:maxdepth: 2
installation
configuration
usage
configuration
examplesapp
......
......@@ -17,7 +17,151 @@
# You should have received a copy of the GNU General Public License
# along with Rodare. If not, see <http://www.gnu.org/licenses/>.
"""Module for Invenio that adds GitLab integration."""
r"""
Module for Invenio that adds GitLab integration.
The Invenio-Gitlab module for Invenio adds GitLab integration to the Invenio
platform. The user links his account on the Invenio platform with its GitLab
account. This module will then gather a list of projects the user owns on
GitLab. If the user activates the preservation of releases for one of his
projects, the Invenio module registers a webhook in GitLab. This webhook is
always triggered, if a new tag is pushed to the repository. If the tag is
considered to be a version tag, the Invenio module creates a new record from
the release in GitLab.
Alembic
-------
If you wish to add the Invenio-Gitlab module to an existing installation, you
can use the provided alembic recipes to migrate your database.
In general, you need to invoke the following command to migrate your DB. Be
careful, in some situations you might need to stamp some revision first:
.. code-block:: bash
$ invenio alembic upgrade heads
Further information is available in the documentation of
`Invenio-DB <https://invenio-db.readthedocs.io/en/latest/alembic.html>`_.
Configure the module
--------------------
Configure a custom GitLab instance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Currently, the module is able to interact with one GitLab instance at a time.
By default, the module is configured to interact with https://gitlab.com. If
you want to configure a custom instance, use the following variable:
.. code-block:: python
GITLAB_BASE_URL = 'https://gitlab.example.de'
Configure OAuth for GitLab
^^^^^^^^^^^^^^^^^^^^^^^^^^
1. *Only necessary if you do not configure for gitlab.com.* Replace
``gitlab.com`` with the address of the GitLab instance you want to
configure in the below code snippet and add it to your configuration.
.. code-block:: python
from invenio_gitlab.config import REMOTE_APP as GITLAB_REMOTE_APP
GITLAB_REMOTE_APP['params']['base_url'] = \
'https://gitlab.example.de/oauth/token'
GITLAB_REMOTE_APP['params']['access_token_url'] = \
'https://gitlab.example.de/oauth/token'
GITLAB_REMOTE_APP['params']['access_token_url'] = \
'https://gitlab.example.de/oauth/authorize'
2. Register the GitLab remote app in ``OAUTHCLIENT_REMOTE_APPS`` and also add
``GITLAB_APP_CREDENTIALS`` to your configuration:
.. code-block:: python
from invenio_gitlab.config import REMOTE_APP as GITLAB_REMOTE_APP
OAUTHCLIENT_REMOTE_APPS = dict(
gitlab=GITLAB_REMOTE_APP,
)
GITLAB_APP_CREDENTIALS = dict(
consumer_key='changeme',
consumer_secret='changeme',
)
3. Go to GitLab and register a new application:
https://gitlab.com/profile/applications.
3.1 Configure the redirect URI to point to:
``CFG_SITE_SECURE_URL/oauth/authorized/gitlab/``
3.2 Select the ``api`` and ``read_user`` scope.
3.3 Save the application.
.. note:: It is possible, that the administrator of your GitLab instance
disallows users to add such applications on their own. Please
contact your GitLab administrator on how to continue, if that is
the case.
4. After registration, copy the *Client ID* and the *Client Secret* and add
those to your instance configuration (``invenio.cfg``):
.. code-block:: python
GITLAB_APP_CREDENTIALS = dict(
consumer_key='<CLIENT ID>',
consumer_secret='<CLIENT SECRET>',
)
5. If everything is configured correctly, you should now be able to see GitLab
listed under the Linked Accounts in the user settings:
http://localhost:5000/account/settings/linkedaccounts
6. Go to ``CFG_SITE_SECURE_URL/oauth/login/gitlab/``. You should be
redirected to GitLab and asked to permit your Invenio instance to access
user information. (e.g. http://localhost:5000/oauth/login/gitlab/).
.. note:: Have a look into the :ref:`configuration-label` section to get a
complete list of configuration options.
Advanced configuration
----------------------
Some Invenio instances might not want to allow sign-up/in to their instance via
GitLab. In this case you need to overwrite the default ``authorized_handler``
to only allow authenticated users to link their accounts.
.. code-block:: python
@oauth_error_handler
def custom_authorized_signup_handler(resp, remote, *args, **kwargs):
# Add these lines to you custom authorized handler.
if not current_user.is_authenticated:
flash(_('Login via GitHub is not permitted.'), category='danger')
return redirect('/')
# Compare the rest of the implementation with
# invenio_oauthclient.handlers:authorized_signup_handler
Now, you can add your custom handler to the ``GITLAB_REMOTE_APP`` in your
configuration:
.. code-block:: python
from invenio_gitlab.config import GITLAB_REMOTE_APP
# add this to your configuration, of course the path needs
# to be customized to your needs
GITLAB_REMOTE_APP['authorized_handler'] = \
'invenio_instance.modules.gitlab.handlers' \
':custom_authorized_signup_handler'
"""
from __future__ import absolute_import, print_function
......
......@@ -155,7 +155,15 @@ class Project(db.Model, Timestamp):
@classmethod
def create(cls, user_id, gitlab_id=None, name=None, regex=None, **kwargs):
"""Create the project."""
"""Create the project.
:param int user_id: User identifier.
:param int gitlab_id: GitLab project identifier.
:param str name: GitLab project full name.
:param str regex: Regular expression used to identify version tags.
:raises: :py:exc:`~.errors.InvalidRegexError`: if the regex cannot be
compiled successfully.
"""
with db.session.begin_nested():
obj = cls(user_id=user_id, gitlab_id=gitlab_id, name=name,
**kwargs)
......@@ -173,16 +181,16 @@ class Project(db.Model, Timestamp):
def get(cls, user_id, gitlab_id=None, name=None, check_owner=True):
"""Return a project.
:param integer user_id: User identifier.
:param integer gitlab_id: GitLab project identifier.
:param int user_id: User identifier.
:param int gitlab_id: GitLab project identifier.
:param str name: GitLab project full name.
:raises: :py:exc:`~sqlalchemy.orm.exc.NoResultFound`: if the project
doesn't exist.
:raises: :py:exc:`~sqlalchemy.orm.exc.MultipleResultsFound`: if
multiple projects with the specified GitLab id and/or name
exist.
:raises: :py:exc:`ProjectAccessError`: if the user is not the owner
of the project.
:raises: :py:exc:`~.errors.ProjectAccessError`: if the user is not the
owner of the project.
"""
project = cls.query.filter((Project.gitlab_id == gitlab_id) |
(Project.name == name)).one()
......@@ -216,7 +224,7 @@ class Project(db.Model, Timestamp):
@property
def enabled(self):
"""Return, if webhooks are enabled for the project."""
"""Return True, if webhooks are enabled for the project."""
return bool(self.hook)
def latest_release(self, status=None):
......
......@@ -102,7 +102,7 @@ require(['jquery', 'js/gitlab/view'], function($, view) {
{%- if not projects %}
<div class="panel-body">
<p>
You have no repositories on GitLab.<br>
You have no projects on GitLab.<br>
Go to <a href="{{config.GITLAB_BASE_URL}}/projects/new">GitLab</a> and create your first or
click Sync-button to synchronize latest changes from GitLab.
</p>
......
......@@ -42,6 +42,7 @@ tests_require = [
extras_require = {
'docs': [
'Sphinx>=1.5.1',
'sphinx_rtd_theme>=0.2.4',
],
'mysql': [
'invenio-db[mysql,versioning]>=1.0.0',
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment