OCA · OCA-git-bot · May 21, 2025 · Jul 21, 2017 · Jul 21, 2017 · Jul 21, 2017
diff --git a/github_connector/README.rst b/github_connector/README.rst
@@ -0,0 +1,395 @@
+================
+Github Connector
+================
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:29c14b59b60246cac8e8b59309bf989c02dd1b2067ce1f395b45d31f5f29944f
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Beta
+.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
+    :alt: License: AGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Finterface--github-lightgray.png?logo=github
+    :target: https://github.com/OCA/interface-github/tree/18.0/github_connector
+    :alt: OCA/interface-github
+.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
+    :target: https://translation.odoo-community.org/projects/interface-github-18-0/interface-github-18-0-github_connector
+    :alt: Translate me on Weblate
+.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
+    :target: https://runboat.odoo-community.org/builds?repo=OCA/interface-github&target_branch=18.0
+    :alt: Try me on Runboat
+
+|badge1| |badge2| |badge3| |badge4| |badge5|
+
+This module allows you to:
+
+- Fetch into Odoo social information from Github (Organizations, Teams,
+  Users)
+- Fetch into Odoo Code structure information from Github (Repositories,
+  Branches)
+- Download source code from Github
+- Analyze repository code from rules previously created
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Installation
+============
+
+To install this addon, you need to install some python dependencies
+
+.. code:: bash
+
+   sudo pip install PyGitHub
+   sudo apt install cloc
+   sudo pip install pathspec
+   sudo pip install GitPython
+
+Analysis source code is generated by
+https://github.com/roskakori/pygount
+
+Configuration
+=============
+
+Once installed, you have to:
+
+1. Open your odoo.conf file and add extra settings to mention Github
+   credentials, and the local path where the source code will be
+   downloaded:
+
+   - ``source_code_local_path = /workspace/source_code/``
+
+Note: you can define the route as environment variable using the key
+SOURCE_CODE_LOCAL_PATH
+
+Note: make sure that Odoo process has read / write access on that folder
+
+   - ``github_token = your_github_access_token``
+
+Note: The login/password auth has been deprecated by GitHub.
+https://docs.github.com/en/rest/overview/other-authentication-methods#via-username-and-password
+
+1. Go to 'Settings' / 'Technical' / 'Parameters' / 'System Parameters'
+   and define the following values:
+
+   1. ``github.max_try``: number of call to the API before an error is
+      raised. The more unstable/slow your connection, the higher should
+      be this value
+   2. ``git.partial_commit_during_analysis``: Set to ``True`` if you
+      want to commit the result of the analysis in the database after
+      each repository analysis. We recommend to set to ``True`` when you
+      perform the initial download (potentially with a lot of
+      repositories) in order to reduce the size of the transaction
+
+   |image|
+
+2. Go to your(s) user(s) form to add them in the new 'Connector Github
+   Manager' groups. The members of this group will have the possibility
+   to run Github synchronization.
+
+Technical Information
+---------------------
+
+This module provides 4 crons that you can enable:
+
+- Synchronize All Organizations and Teams (``cron_update_organization``)
+- Synchronize Branches List for All repositories
+  (``cron_update_branch_list``)
+- Download Source Code for All Github Branches (``cron_download_code``)
+- Analyze Source Code for All Github Branches (``cron_analyze_code``)
+
+.. |image| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_settings.png
+
+Usage
+=====
+
+Initial upload from Github
+--------------------------
+
+To fetch information from Github, you have to:
+
+1. go to 'Github' / 'Settings' / 'Sync Object'
+
+2. Select the object type you want to synchronize and its Gthub name
+
+   |sync_organization|
+
+3. Once done for your organization(s), go to 'Github' / 'Github
+   Commnunity' / 'Organizations'
+
+   |github_organization_kanban|
+
+4. Optionally, once organization is created, you can create series for
+   your projects. Go to 'Github' / 'Organizations' / click on your
+   organization / 'Organization Series' Tabs
+
+   |github_organization_series|
+
+Select branches to download
+---------------------------
+
+This setting will prevent to download undesired branches, downloading
+only main branches (releases):
+
+1. In the 'Settings' tab, set repositories you don't want to download
+   (or repositories you want to download). If 'Specific repositories' is
+   set, 'Ignored Repositories' value is ignored.
+
+2. In the 'Settings' tab, set the URL of the 'External Services' you use
+   for Continuous Integration and Coverage.
+
+   |github_organization_external_services|
+
+3. Once done, click on buttons 'Syncs', to synchronize repositories,
+   teams and members. (This process can take a while depending of your
+   size)
+
+   |github_organization_sync_buttons|
+
+Team / members synchronization
+------------------------------
+
+You can synchronize members teams:
+
+1. Go to 'Teams' / tree view / 'Actions' / 'Update from Github'.
+
+   |github_team_kanban|
+
+2. In each team, you can see the members list and the role of the
+   members
+
+   |github_team_partner_kanban|
+
+3. In each team, you can see the repositories list but not the
+   permissions of the team. (See 'Known Issues' Section)
+
+   |github_team_repository_kanban|
+
+Repositories synchronization
+----------------------------
+
+You can synchronize the branches of your repositories:
+
+1. Go to 'Repositories' / tree view / 'Actions' / 'Update from Github'
+
+   |github_repository_kanban|
+
+2. In each repository, you can see the main branches list and the size
+   of code source.
+
+   |github_repository_branch_kanban|
+
+Fetching the source code
+------------------------
+
+Finally, you can download locally the source code of all your branches:
+
+1. Go to 'Repository Branches' / tree view / 'Actions' / 'Download and
+   Analyse Source Code'.
+
+   |wizard_download_analyze|
+
+2. In the tree view you can update manually source code or refresh
+   analysis.
+
+   |github_repository_branch_list|
+
+Analysis source code
+--------------------
+
+It's possible to create custom analysis rules that relate to a GitHub
+organization, GitHub repository and/or GitHub repository branch to
+analyze code.
+
+1. Go to 'Settings' / 'Analysis rule groups' and create records that
+   allow to organize the rules
+2. Go to 'Settings' / 'Analysis rules' and create rules, for example:
+
+..
+
+   1. Name: All code, Group: General, Paths: ``*``
+   2. Name: Python code, Group: General, Paths: ``*.py``
+   3. Name: Xml code, Group: General, Paths: ``*.xml``
+   4. Name: Repository 1, Group: Custom, Paths: /path/
+
+Note: Paths field in 'Analysis rule' allow to put multiple paths for
+line, path format is according to
+https://git-scm.com/docs/gitignore#_pattern_format
+
+1. Go to *GitHub > GitHub Community > Organizations* and define Analysis
+   rules (optional)
+2. Go to *GitHub > GitHub Repository > Repositories* and define Analysis
+   rules (optional)
+3. Go to *GitHub > GitHub Repository > Repository Branches* and define
+   Analysis rules (optional)
+
+Analysis source code is executed when 'Update Source Code Analysis'
+button in some 'Repository Branch', get all the Analysis rules
+(Repository + Organization) and analyze code and generate info about it
+Other option to Analysis source code is in cron called 'Analyze Source
+Code for All Github Branches'
+
+You can see in 'Repository Branch' / 'Code Analysis' the info obtained
+from analysis rules.
+
+Data creation in Github
+-----------------------
+
+You have the possibility to creates two items in Github directly from
+Odoo
+
+1. Teams:
+
+   1. Go to 'Settings' / 'Create Team in Github'.
+   2. Set the information and click on Create in Github.
+   3. Odoo will try to create the team. If access right and datas are
+      correct, the creation will be done directly in Github
+   4. Later on, a synchronization will be performed, to create the
+      according team in the Odoo instance.
+
+   |wizard_create_team|
+
+2. Repositories:
+
+   1. Go to 'Settings' / 'Create Team in Github'.
+   2. Set the information and click on Create in Github.
+
+   |wizard_create_repository|
+
+Note
+----
+
+Analysis in this module is basic: for the time being, it just gives
+branches size.
+
+Nevertheless, you can develop an extra Odoo Custom module to extend
+analysis function and get extra statistics, depending on your needs.
+
+In that way, you can see the module github_connector_odoo, if your
+repositories contain Odoo modules.
+
+Reporting
+---------
+
+This module provides several reports
+
+**Branches by Serie**
+
+|reporting_branches_by_serie|
+
+**Sizes by Serie**
+
+|reporting_sizes_by_serie|
+
+**Repository branch analysis rule**
+
+|github_repository_branch_rule_info_report|
+
+.. |sync_organization| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/sync_organization.png
+.. |github_organization_kanban| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_organization_kanban.png
+.. |github_organization_series| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_organization_series.png
+.. |github_organization_external_services| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_organization_external_services.png
+.. |github_organization_sync_buttons| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_organization_sync_buttons.png
+.. |github_team_kanban| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_team_kanban.png
+.. |github_team_partner_kanban| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_team_partner_kanban.png
+.. |github_team_repository_kanban| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_team_repository_kanban.png
+.. |github_repository_kanban| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_repository_kanban.png
+.. |github_repository_branch_kanban| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_repository_branch_kanban.png
+.. |wizard_download_analyze| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/wizard_download_analyze.png
+.. |github_repository_branch_list| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_repository_branch_list.png
+.. |wizard_create_team| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/wizard_create_team.png
+.. |wizard_create_repository| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/wizard_create_repository.png
+.. |reporting_branches_by_serie| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/reporting_branches_by_serie.png
+.. |reporting_sizes_by_serie| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/reporting_sizes_by_serie.png
+.. |github_repository_branch_rule_info_report| image:: https://raw.githubusercontent.com/OCA/interface-github/18.0/github_connector/static/description/github_repository_branch_rule_info_report.png
+
+Known issues / Roadmap
+======================
+
+- For the time being, Github API doesn't provide some informations that
+  are available by the classic UI, that includes:
+
+  1. team hierarchy: the field is present in the model
+     github_team.parent_id, but unused.
+
+- Possible improvements:
+
+  1. Create a new module github_connector_website, that could display
+     teams / repositories / branches informations for non logged users.
+  2. Analyze commits (author, quantity by series, etc...): this feature
+     has been partially implemented in a V8.0 PR.
+  3. Synchronize Pull Request, Issues, Comments: this feature has been
+     partially implemented in a V8.0 PR.
+
+- Refactor the github connector:
+
+  A python library called PyGitHub is available. It could be interesting
+  to use it, instead of using custom code. However, this lib doesn't
+  provide good access to child object, generating for the time being,
+  unnecessary API calls. For example, updating a repository should call
+  before a call to the parent organization (The current module is so
+  faster).
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/interface-github/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+`feedback <https://github.com/OCA/interface-github/issues/new?body=module:%20github_connector%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Authors
+-------
+
+* GRAP
+* Akretion
+* Tecnativa
+
+Contributors
+------------
+
+- Sylvain LE GAL (https://twitter.com/legalsylvain)
+- Sébastien BEAU (sebastien.beau@akretion.com)
+- Benoît GUILLOT (benoit.guillot@akretion.com)
+- Enrique Martín (enriquemartin@digital5.es)
+- `Tecnativa <https://www.tecnativa.com>`__:",
+
+  - Pedro M. Baeza
+  - Vicent Cubells
+  - Alexandre Díaz
+  - Ernesto Tejeda
+  - Carlos Roca
+  - Víctor Martínez
+  - João Marques
+  - Carolina Fernandez
+
+Maintainers
+-----------
+
+This module is maintained by the OCA.
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+This module is part of the `OCA/interface-github <https://github.com/OCA/interface-github/tree/18.0/github_connector>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
diff --git a/github_connector/__init__.py b/github_connector/__init__.py
@@ -0,0 +1,3 @@
+from . import models
+from . import report
+from . import wizards