GitHub App integration for Kiwi TCMS
====================================
.. image:: https://coveralls.io/repos/github/kiwitcms/github-app/badge.svg?branch=master
:target: https://coveralls.io/github/kiwitcms/github-app?branch=master
.. image:: https://pyup.io/repos/github/kiwitcms/github-app/shield.svg
:target: https://pyup.io/repos/github/kiwitcms/github-app/
:alt: Python updates
.. image:: https://tidelift.com/badges/package/pypi/kiwitcms-github-app
:target: https://tidelift.com/subscription/pkg/pypi-kiwitcms-github-app?utm_source=pypi-kiwitcms-github-app&utm_medium=github&utm_campaign=readme
:alt: Tidelift
.. image:: https://opencollective.com/kiwitcms/tiers/sponsor/badge.svg?label=sponsors&color=brightgreen
:target: https://opencollective.com/kiwitcms#contributors
:alt: Become a sponsor
.. image:: https://img.shields.io/twitter/follow/KiwiTCMS.svg
:target: https://twitter.com/KiwiTCMS
:alt: Kiwi TCMS on Twitter
Introduction
------------
This package provides the GitHub App integration for
`Kiwi TCMS Enterprise <https://github.com/MrSenko/kiwitcms-enterprise/>`_
and is designed to work only for multi-tenant environments!
You don't need this add-on in order to run Kiwi TCMS without extended
GitHub integration!
Communication from GitHub to this plugin is via webhooks.
Plugin behavior:
- Auto-configure which tenant to use for database operations, either
'public' or a single private tenant to which user has access.
- If unable to auto-configure display warning and redirect to configuration
page once the GitHub account who installed this integration onto their
GitHub repository logs into Kiwi TCMS
- Existing & newly created repositories are added as products in Kiwi TCMS
- BugSystem records are automatically configured for repositories
- Fork repositories are skipped
- Newly created git tags are added as product versions in Kiwi TCMS
See `Issues <https://github.com/kiwitcms/github-app/issues>`_ for other ideas!
Installation
------------
::
pip install kiwitcms-github-app
inside Kiwi TCMS's docker image and make sure the following settings are configured::
AUTHENTICATION_BACKENDS = [
'social_core.backends.github.GithubAppAuth',
...
]
SOCIAL_AUTH_GITHUB_APP_KEY = 'xxxxxx'
SOCIAL_AUTH_GITHUB_APP_SECRET = 'yyy'
KIWI_GITHUB_APP_SECRET = b'your-webhook-secret'
KIWI_GITHUB_APP_ID = 123456
KIWI_GITHUB_APP_PRIVATE_KEY = """-----BEGIN RSA PRIVATE KEY-----
+++++++++base64-encoded-private-key+++++++
-----END RSA PRIVATE KEY-----"""
everything else will be taken care for by Kiwi TCMS plugin loading code!
GitHub App configuration
------------------------
This plugin needs an existing GitHub App application with the following
configuration:
- User authorization callback URL: https://tcms.example.com/complete/github-app/
- Request user authorization (OAuth) during installation - True
- Webhook Active - True
- Webhook URL - https://tcms.example.com/kiwitcms_github_app/webhook/
- Webhook Secret - <the value of KIWI_GITHUB_APP_SECRET>
- SSL verification - Enabled
Then configure how the application interacts with GitHub:
- Repository permissions:
- Contents: Read-only
- Issues: Read & write (required for 1-click bug report on private repos)
- Metadata: Read-only
- User permissions:
- Email addresses: Read-only
- Subscribe to events:
- Meta
- Create
- Repository
Changelog
---------
v1.7.0 (06 May 2024)
~~~~~~~~~~~~~~~~~~~~
- Pin indirect requirements to reduce the chance of installing vulnerable
dependencies
- Remove the wrapper ``GithubKiwiTCMSBot()`` class
- Simplify ``self.requester`` override in ``PatchedGithub()`` class
- Start using the new GitHub Auth parameters introduced in PyGithub==1.59.0
v1.6.0 (15 Jan 2024)
~~~~~~~~~~~~~~~~~~~~
- 1-click bug report will now use ``execution.build.version.product`` instead
of ``execution.run.plan.product`` following changes in Kiwi TCMS, see:
<https://github.com/kiwitcms/Kiwi/commit/48a33a71e664c8c3ed2ceb298b5f1e19d0bddb52>_
and `PR #3439 <https://github.com/kiwitcms/Kiwi/pull/3439>`_ for more details
- Require minimum version of several transitive dependencies,
``certifi>=2023.7.22``, ``cryptography>=41.0.4``, ``pyjwt>=2.4.0``, ``requests>=2.31.0``
in order to minimize exposure to known security vulnerabilities
- Build & test with Python 3.11
- Start testing with psycopg3
- Small updates around test jobs & CI
v1.5.1 (28 Mar 2023)
~~~~~~~~~~~~~~~~~~~~
- Unpin PyGithub dependency
- Add more tests
v1.5.0 (24 Feb 2023)
~~~~~~~~~~~~~~~~~~~~
- Refactor code so it works with PyGithub==1.58.0
- Remove PatchedGithubIntegration class
- Add sanity tests for upstream/downstream interfaces for PyGithub
v1.4.1 (13 Feb 2023)
~~~~~~~~~~~~~~~~~~~~
- Adjust arguments for latest github.Github implementation
- Raise RuntimeError instead of Exception
v1.4.0 (05 Sep 2022)
~~~~~~~~~~~~~~~~~~~~
- Don't ask user to configure GitHub App if they are not tenant owner. Breaks
an endless loop cycle in case tenant creation goes wrong
- Specify 30 sec timeout for internal HTTP requests
- Improvements to CI
v1.3.3 (31 Jan 2022)
~~~~~~~~~~~~~~~~~~~~
- Fix for GitHub exceptions. Fixes
`KIWI-TCMS-HH <https://sentry.io/organizations/kiwitcms/issues/2959079667>`_
v1.3.2 (05 Jan 2022)
~~~~~~~~~~~~~~~~~~~~
- Don't crash on 404 from GitHub. Fixes
`KIWI-TCMS-EA <https://sentry.io/organizations/kiwitcms/issues/1869016907/>`_
- Workaround upstream <https://github.com/PyGithub/PyGithub/pull/2079>. Fixes
`KIWI-TCMS-HD <https://sentry.io/organizations/kiwitcms/issues/2835963408>`_
v1.3.1 (04 Oct 2021)
~~~~~~~~~~~~~~~~~~~~
- Adjust 2 parameters for changes introduced in PyGithub 1.55
v1.3.0 (14 Feb 2021)
~~~~~~~~~~~~~~~~~~~~
- Migrate to Python 3.8
- Always test with the latest Kiwi TCMS version
- Adjustments to the internal test suite now that Kiwi TCMS is available via
source
- Prevent crash if ``uid`` field is not a number to make it work with Keycloak
v1.2.4 (14 Feb 2021)
~~~~~~~~~~~~~~~~~~~~
- Don't cause ISE in case of race conditions between webhooks
- Fix ISE for existing Version
v1.2.3 (25 Jan 2021)
~~~~~~~~~~~~~~~~~~~~
- Allow POST request (web hooks) without CSRF token
v1.2.2 (08 Dec 2020)
~~~~~~~~~~~~~~~~~~~~
- Update for newer PyGithub
v1.2.1 (17 Sep 2020)
~~~~~~~~~~~~~~~~~~~~
- Require login for views.Resync()
v1.2 (13 Sep 2020)
~~~~~~~~~~~~~~~~~~
- Adjusted to work with Django 3.1 and Kiwi TCMS > 8.6
- Replace deprecated ``url()`` with ``re_path()``
- Migrate the ``payload`` field to newer ``models.JSONField`` type
- Setting ``PUBLIC_VIEWS`` is removed in Kiwi TCMS so remove the
automatic adjustment
- Make error messages for missing AppInst more clear
- Remove redundant if condition in Resync()
- Update translation strings
- Update documentation around GitHub permission requirements for
1-click bug report
v1.1 (05 Aug 2020)
~~~~~~~~~~~~~~~~~~
- Add GitHub issue-tracker integration which authenticates as the installed app.
Fixes `Issue #25 <https://github.com/kiwitcms/github-app/issues/25>`_
- Configure BugSystem for new repos. Fixes
`Issue #15 <https://github.com/kiwitcms/github-app/issues/15>`_
- Create Product & BugSystem records when installation_repositores change.
Fixes `Issue #21 <https://github.com/kiwitcms/github-app/issues/21>`_
- Trigger resync from GitHub via menu. Fixes
`Issue #19 <https://github.com/kiwitcms/github-app/issues/19>`_
- Trigger resync from GitHub after AppInstallation is configured. Fixes
`Issue #20 <https://github.com/kiwitcms/github-app/issues/20>`_
- Database: Add ``AppInstallation.settings_url`` field
- Link to the correct URL for GitHub settings. Fixes
`Issue #33 <https://github.com/kiwitcms/github-app/issues/33>`_
- Require user to be logged in for ApplicationEdit. Fixes
`Issue #36 <https://github.com/kiwitcms/github-app/issues/36>`_
- Update translation strings
- Add more tests
v1.0 (13 Apr 2020)
~~~~~~~~~~~~~~~~~~
- Install settings overrides under ``tcms_settings_dir/``
(compatible with Kiwi TCMS v8.2 or later):
- does not need ``MIDDLEWARE`` and ``PUBLIC_VIEWS`` override anymore
- Remove ``GithubAppAuth`` backend, shipped with social-auth-core v3.3.0
- Fix a redirect to use the correct name of our social_core backend
v0.0.5 (19 Feb 2020)
~~~~~~~~~~~~~~~~~~~~
- Address GitHub API deprecation not yet fixed in social-auth-core
v0.0.4 (25 Dec 2019)
~~~~~~~~~~~~~~~~~~~~
- Do not fail if product already exists
- Do not fail if repository doesn't have description
- Search UserSocialAuth by uid and provider
v0.0.1 (24 Dec 2019)
~~~~~~~~~~~~~~~~~~~~
- initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/kiwitcms/github-app/",
"name": "kiwitcms-github-app",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Kiwi TCMS",
"author_email": "info@kiwitcms.org",
"download_url": "https://files.pythonhosted.org/packages/0b/f9/9fc24748b740bc44230e57cfc37501bf40c7e35b73617bdc3c9489c2568b/kiwitcms-github-app-1.7.0.tar.gz",
"platform": null,
"description": "GitHub App integration for Kiwi TCMS\n====================================\n\n.. image:: https://coveralls.io/repos/github/kiwitcms/github-app/badge.svg?branch=master\n :target: https://coveralls.io/github/kiwitcms/github-app?branch=master\n\n.. image:: https://pyup.io/repos/github/kiwitcms/github-app/shield.svg\n :target: https://pyup.io/repos/github/kiwitcms/github-app/\n :alt: Python updates\n\n.. image:: https://tidelift.com/badges/package/pypi/kiwitcms-github-app\n :target: https://tidelift.com/subscription/pkg/pypi-kiwitcms-github-app?utm_source=pypi-kiwitcms-github-app&utm_medium=github&utm_campaign=readme\n :alt: Tidelift\n\n.. image:: https://opencollective.com/kiwitcms/tiers/sponsor/badge.svg?label=sponsors&color=brightgreen\n :target: https://opencollective.com/kiwitcms#contributors\n :alt: Become a sponsor\n\n.. image:: https://img.shields.io/twitter/follow/KiwiTCMS.svg\n :target: https://twitter.com/KiwiTCMS\n :alt: Kiwi TCMS on Twitter\n\n\nIntroduction\n------------\n\nThis package provides the GitHub App integration for\n`Kiwi TCMS Enterprise <https://github.com/MrSenko/kiwitcms-enterprise/>`_\nand is designed to work only for multi-tenant environments!\nYou don't need this add-on in order to run Kiwi TCMS without extended\nGitHub integration!\n\nCommunication from GitHub to this plugin is via webhooks.\n\nPlugin behavior:\n\n- Auto-configure which tenant to use for database operations, either\n 'public' or a single private tenant to which user has access.\n- If unable to auto-configure display warning and redirect to configuration\n page once the GitHub account who installed this integration onto their\n GitHub repository logs into Kiwi TCMS\n- Existing & newly created repositories are added as products in Kiwi TCMS\n- BugSystem records are automatically configured for repositories\n- Fork repositories are skipped\n- Newly created git tags are added as product versions in Kiwi TCMS\n\n\nSee `Issues <https://github.com/kiwitcms/github-app/issues>`_ for other ideas!\n\n\nInstallation\n------------\n\n::\n\n pip install kiwitcms-github-app\n\ninside Kiwi TCMS's docker image and make sure the following settings are configured::\n\n AUTHENTICATION_BACKENDS = [\n 'social_core.backends.github.GithubAppAuth',\n ...\n ]\n SOCIAL_AUTH_GITHUB_APP_KEY = 'xxxxxx'\n SOCIAL_AUTH_GITHUB_APP_SECRET = 'yyy'\n KIWI_GITHUB_APP_SECRET = b'your-webhook-secret'\n KIWI_GITHUB_APP_ID = 123456\n KIWI_GITHUB_APP_PRIVATE_KEY = \"\"\"-----BEGIN RSA PRIVATE KEY-----\n +++++++++base64-encoded-private-key+++++++\n -----END RSA PRIVATE KEY-----\"\"\"\n\neverything else will be taken care for by Kiwi TCMS plugin loading code!\n\n\nGitHub App configuration\n------------------------\n\nThis plugin needs an existing GitHub App application with the following\nconfiguration:\n\n- User authorization callback URL: https://tcms.example.com/complete/github-app/\n- Request user authorization (OAuth) during installation - True\n- Webhook Active - True\n- Webhook URL - https://tcms.example.com/kiwitcms_github_app/webhook/\n- Webhook Secret - <the value of KIWI_GITHUB_APP_SECRET>\n- SSL verification - Enabled\n\nThen configure how the application interacts with GitHub:\n\n- Repository permissions:\n\n - Contents: Read-only\n - Issues: Read & write (required for 1-click bug report on private repos)\n - Metadata: Read-only\n\n- User permissions:\n\n - Email addresses: Read-only\n\n- Subscribe to events:\n\n - Meta\n - Create\n - Repository\n\n\nChangelog\n---------\n\nv1.7.0 (06 May 2024)\n~~~~~~~~~~~~~~~~~~~~\n\n- Pin indirect requirements to reduce the chance of installing vulnerable\n dependencies\n- Remove the wrapper ``GithubKiwiTCMSBot()`` class\n- Simplify ``self.requester`` override in ``PatchedGithub()`` class\n- Start using the new GitHub Auth parameters introduced in PyGithub==1.59.0\n\n\nv1.6.0 (15 Jan 2024)\n~~~~~~~~~~~~~~~~~~~~\n\n- 1-click bug report will now use ``execution.build.version.product`` instead\n of ``execution.run.plan.product`` following changes in Kiwi TCMS, see:\n <https://github.com/kiwitcms/Kiwi/commit/48a33a71e664c8c3ed2ceb298b5f1e19d0bddb52>_\n and `PR #3439 <https://github.com/kiwitcms/Kiwi/pull/3439>`_ for more details\n- Require minimum version of several transitive dependencies,\n ``certifi>=2023.7.22``, ``cryptography>=41.0.4``, ``pyjwt>=2.4.0``, ``requests>=2.31.0``\n in order to minimize exposure to known security vulnerabilities\n- Build & test with Python 3.11\n- Start testing with psycopg3\n- Small updates around test jobs & CI\n\n\nv1.5.1 (28 Mar 2023)\n~~~~~~~~~~~~~~~~~~~~\n\n- Unpin PyGithub dependency\n- Add more tests\n\n\nv1.5.0 (24 Feb 2023)\n~~~~~~~~~~~~~~~~~~~~\n\n- Refactor code so it works with PyGithub==1.58.0\n- Remove PatchedGithubIntegration class\n- Add sanity tests for upstream/downstream interfaces for PyGithub\n\n\nv1.4.1 (13 Feb 2023)\n~~~~~~~~~~~~~~~~~~~~\n\n- Adjust arguments for latest github.Github implementation\n- Raise RuntimeError instead of Exception\n\n\nv1.4.0 (05 Sep 2022)\n~~~~~~~~~~~~~~~~~~~~\n\n- Don't ask user to configure GitHub App if they are not tenant owner. Breaks\n an endless loop cycle in case tenant creation goes wrong\n- Specify 30 sec timeout for internal HTTP requests\n- Improvements to CI\n\n\nv1.3.3 (31 Jan 2022)\n~~~~~~~~~~~~~~~~~~~~\n\n- Fix for GitHub exceptions. Fixes\n `KIWI-TCMS-HH <https://sentry.io/organizations/kiwitcms/issues/2959079667>`_\n\n\nv1.3.2 (05 Jan 2022)\n~~~~~~~~~~~~~~~~~~~~\n\n- Don't crash on 404 from GitHub. Fixes\n `KIWI-TCMS-EA <https://sentry.io/organizations/kiwitcms/issues/1869016907/>`_\n- Workaround upstream <https://github.com/PyGithub/PyGithub/pull/2079>. Fixes\n `KIWI-TCMS-HD <https://sentry.io/organizations/kiwitcms/issues/2835963408>`_\n\n\nv1.3.1 (04 Oct 2021)\n~~~~~~~~~~~~~~~~~~~~\n\n- Adjust 2 parameters for changes introduced in PyGithub 1.55\n\n\nv1.3.0 (14 Feb 2021)\n~~~~~~~~~~~~~~~~~~~~\n\n- Migrate to Python 3.8\n- Always test with the latest Kiwi TCMS version\n- Adjustments to the internal test suite now that Kiwi TCMS is available via\n source\n- Prevent crash if ``uid`` field is not a number to make it work with Keycloak\n\n\nv1.2.4 (14 Feb 2021)\n~~~~~~~~~~~~~~~~~~~~\n\n- Don't cause ISE in case of race conditions between webhooks\n- Fix ISE for existing Version\n\n\nv1.2.3 (25 Jan 2021)\n~~~~~~~~~~~~~~~~~~~~\n\n- Allow POST request (web hooks) without CSRF token\n\n\nv1.2.2 (08 Dec 2020)\n~~~~~~~~~~~~~~~~~~~~\n\n- Update for newer PyGithub\n\n\nv1.2.1 (17 Sep 2020)\n~~~~~~~~~~~~~~~~~~~~\n\n- Require login for views.Resync()\n\n\nv1.2 (13 Sep 2020)\n~~~~~~~~~~~~~~~~~~\n\n- Adjusted to work with Django 3.1 and Kiwi TCMS > 8.6\n- Replace deprecated ``url()`` with ``re_path()``\n- Migrate the ``payload`` field to newer ``models.JSONField`` type\n- Setting ``PUBLIC_VIEWS`` is removed in Kiwi TCMS so remove the\n automatic adjustment\n- Make error messages for missing AppInst more clear\n- Remove redundant if condition in Resync()\n- Update translation strings\n- Update documentation around GitHub permission requirements for\n 1-click bug report\n\n\nv1.1 (05 Aug 2020)\n~~~~~~~~~~~~~~~~~~\n\n- Add GitHub issue-tracker integration which authenticates as the installed app.\n Fixes `Issue #25 <https://github.com/kiwitcms/github-app/issues/25>`_\n- Configure BugSystem for new repos. Fixes\n `Issue #15 <https://github.com/kiwitcms/github-app/issues/15>`_\n- Create Product & BugSystem records when installation_repositores change.\n Fixes `Issue #21 <https://github.com/kiwitcms/github-app/issues/21>`_\n- Trigger resync from GitHub via menu. Fixes\n `Issue #19 <https://github.com/kiwitcms/github-app/issues/19>`_\n- Trigger resync from GitHub after AppInstallation is configured. Fixes\n `Issue #20 <https://github.com/kiwitcms/github-app/issues/20>`_\n- Database: Add ``AppInstallation.settings_url`` field\n- Link to the correct URL for GitHub settings. Fixes\n `Issue #33 <https://github.com/kiwitcms/github-app/issues/33>`_\n- Require user to be logged in for ApplicationEdit. Fixes\n `Issue #36 <https://github.com/kiwitcms/github-app/issues/36>`_\n- Update translation strings\n- Add more tests\n\n\nv1.0 (13 Apr 2020)\n~~~~~~~~~~~~~~~~~~\n\n- Install settings overrides under ``tcms_settings_dir/``\n (compatible with Kiwi TCMS v8.2 or later):\n\n - does not need ``MIDDLEWARE`` and ``PUBLIC_VIEWS`` override anymore\n- Remove ``GithubAppAuth`` backend, shipped with social-auth-core v3.3.0\n- Fix a redirect to use the correct name of our social_core backend\n\n\nv0.0.5 (19 Feb 2020)\n~~~~~~~~~~~~~~~~~~~~\n\n- Address GitHub API deprecation not yet fixed in social-auth-core\n\n\nv0.0.4 (25 Dec 2019)\n~~~~~~~~~~~~~~~~~~~~\n\n- Do not fail if product already exists\n- Do not fail if repository doesn't have description\n- Search UserSocialAuth by uid and provider\n\n\nv0.0.1 (24 Dec 2019)\n~~~~~~~~~~~~~~~~~~~~\n\n- initial release\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "GitHub App integration for Kiwi TCMS",
"version": "1.7.0",
"project_urls": {
"Homepage": "https://github.com/kiwitcms/github-app/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9619b129316fcc76fc857de9e1aa1d8102c08661b60ba0ada3d021ffd26104db",
"md5": "859e645410b05889488bebbbc1d9a6b5",
"sha256": "4bd883e83bdf9d808bd1b5bd573dba033da26330cfe072e67ecc5aeefc4e800d"
},
"downloads": -1,
"filename": "kiwitcms_github_app-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "859e645410b05889488bebbbc1d9a6b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 31603,
"upload_time": "2024-05-06T10:08:13",
"upload_time_iso_8601": "2024-05-06T10:08:13.133226Z",
"url": "https://files.pythonhosted.org/packages/96/19/b129316fcc76fc857de9e1aa1d8102c08661b60ba0ada3d021ffd26104db/kiwitcms_github_app-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0bf99fc24748b740bc44230e57cfc37501bf40c7e35b73617bdc3c9489c2568b",
"md5": "3d9bfe2ea5bf4aa8b4fc6bd0659a2a0a",
"sha256": "89a5b097218204fa0e64dee219f335163502b5123daa2e9c0aba278d0ba4fef8"
},
"downloads": -1,
"filename": "kiwitcms-github-app-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "3d9bfe2ea5bf4aa8b4fc6bd0659a2a0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26826,
"upload_time": "2024-05-06T10:08:15",
"upload_time_iso_8601": "2024-05-06T10:08:15.086476Z",
"url": "https://files.pythonhosted.org/packages/0b/f9/9fc24748b740bc44230e57cfc37501bf40c7e35b73617bdc3c9489c2568b/kiwitcms-github-app-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 10:08:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiwitcms",
"github_project": "github-app",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "kiwitcms-github-app"
}
JSON
