Github Connector
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
Table of contents
Configuration
Once installed, you have to:
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
or
- github_login = your_github_login
- github_password = your_github_password
Note: if token and login/password are provided, the token will be used. The login/password auth will be deprecated by GitHub in the future.
Go to ‘Settings’ / ‘Technical’ / ‘Parameters’ / ‘System Parameters’ and define the following values:
- 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
- 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
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)
Usage
Initial upload from Github
To fetch information from Github, you have to:
go to ‘Github’ / ‘Settings’ / ‘Sync Object’
Select the object type you want to synchronize and its Gthub name
Once done for your organization(s), go to ‘Github’ / ‘Github Commnunity’ / ‘Organizations’
Optionally, once organization is created, you can create series for your projects. Go to ‘Github’ / ‘Organizations’ / click on your organization / ‘Organization Series’ Tabs
Select branches to download
This setting will prevent to download undesired branches, downloading only main branches (releases):
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.
In the ‘Settings’ tab, set the URL of the ‘External Services’ you use for Continuous Integration and Coverage.
Once done, click on buttons ‘Syncs’, to synchronize repositories, teams and members. (This process can take a while depending of your size)
Team / members synchronization
You can synchronize members teams:
Go to ‘Teams’ / tree view / ‘Actions’ / ‘Update from Github’.
In each team, you can see the members list and the role of the members
In each team, you can see the repositories list but not the permissions of the team. (See ‘Known Issues’ Section)
Repositories synchronization
You can synchronize the branches of your repositories:
Go to ‘Repositories’ / tree view / ‘Actions’ / ‘Update from Github’
In each repository, you can see the main branches list and the size of code source.
Fetching the source code
Finally, you can download locally the source code of all your branches:
Go to ‘Repository Branches’ / tree view / ‘Actions’ / ‘Download and Analyse Source Code’.
In the tree view you can update manually source code or refresh analysis.
Download a private repository
If you want to fetch the source code from a private repository, you need a token (instead of login/password) with the right scopes:
Go to ‘Github Account’ / ‘Settings’ / ‘Developer settings’ / ‘Personal access tokens’ / ‘Generate new token’.
In the ‘New personal access token’ you have to select ‘repo scope’.
Add one of these scopes to your token:
- (no scope) : Grants read-only access to public information (includes public user profile info, public repository info, and gists).
- repo : Grants full access to private and public repositories. See here why is this needed.
Secure storage:
- For security, the git code (source_code_local_path) and the config file (odoo.conf) should be found in a secure storage where only the Odoo process has read and write capabilities.
Otherwise, the code and token (or login/password if you use those – don’t do it!) may be exposed.
Data creation in Github
You have the possibility to creates two items in Github directly from Odoo
Teams:
- Go to ‘Settings’ / ‘Create Team in Github’.
- Set the information and click on Create in Github.
- Odoo will try to create the team. If access right and datas are correct, the creation will be done directly in Github
- Later on, a synchronization will be performed, to create the according team in the Odoo instance.
Repositories:
- Go to ‘Settings’ / ‘Create Team in Github’.
- Set the information and click on Create in Github.
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.
Known issues / Roadmap
For the time being, Github API doesn’t provide some informations that are available by the classic UI, that includes:
- team hierarchy: the field is present in the model github_team.parent_id, but unused.
Possible improvements:
- Create a new module github_connector_website, that could display teams / repositories / branches informations for non logged users.
- Analyze commits (author, quantity by series, etc…): this feature has been partially implemented in a V8.0 PR.
- 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).
``sudo pip install PyGitHub``
Bug Tracker
Bugs are tracked on 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.
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 ([email protected])
Benoît GUILLOT ([email protected])
Enrique Martín ([email protected])
-
- Pedro M. Baeza
- Vicent Cubells
- Carlos Roca
- Víctor Martínez
Maintainers
This module is maintained by the OCA.
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 project on GitHub.
You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
Python dependencies
| Package | Version | Secured | ||
|---|---|---|---|---|
| requests | 2.22.0 | |||
| GitPython | 3.1.43 |