.. include:: /Includes.rst.txt .. index:: Webhooks .. _webhook: ======= Webhook ======= This section describes how to add webhooks for auto rendering to a repository. The system supports Git as VCS (Version Control System), and the following hosts: - :ref:`webhook-github` - :ref:`webhook-bitbucket-cloud` and Bitbucket self-hosted - :ref:`GitLab Cloud ` and :ref:`GitLab self-hosted ` .. contents:: Table of Contents :local: .. index:: Webhooks; Approval .. _approval-intercept: Approval ======== In order to render documentation, the TYPO3 Documentation Team needs to approve each new extension when requesting rendering for the first time. In order to approve an extension, the following things need to apply: #. The extension needs to be published in TER under the same extension key as claimed by :ref:`t3coreapi:composer.json `. #. The Git Repository is referenced from TER detail view page. This is necessary to prevent misuse of the infrastructure and extension names. In case the approval takes too long, request the approval within the Slack channel `#typo3-documentation `_. Registration for Slack is available at `my.typo3.org `__. .. _foreign-setups: Foreign setups ============== In some cases one might use a different host than the one mentioned above. Or the file structure does not match the structure of an TYPO3 extension. In such cases a mirror to one of the supported hosts must be setup. Otherwise it is not possible to enable documentation rendering on docs.typo3.org. .. _webhook-how-webhook-works: How webhooks work ================= If it's your first time working with webhooks, take a look at `GitHub developer `_. The configuration below triggers rendering only on push events. In order to test the integration, a push to `main` branch or `documentation-draft` branch can be used, see :ref:`migrate-branches`. .. note:: Documentation rendering is only triggered for versions affected by push event. Not the whole repository will be rendered each time. If a push event for branch 7.8 is triggered, only this version will be rendered. .. _webhook-legacy: Legacy webhook ============== If the repository already had a hook, this is considered deprecated. A compatibility layer is still in place, but will be removed in the future. .. index:: Webhooks; GitHub .. _webhook-github: GitHub ====== Add auto rendering for a repository via GitHub webhook in five steps: .. rst-class:: bignums-xxl #. Go to "Settings" tab within the repository .. figure:: /Images/webhook/github/repository-start.png :width: 932 #. Go to "Webhooks" section within the repository settings .. figure:: /Images/webhook/github/settings-tab.png :width: 932 #. Add webhook .. figure:: /Images/webhook/github/webhook-section.png :width: 932 #. Fill in webhook configuration #. Configure URL :samp:`https://docs-hook.typo3.org` for field "Payload URL". #. Select ``application/json`` as "Content type". #. Enable "SSL verification". #. Select ``Just the push event.`` for "Which events would you like to trigger this webhook?". #. Enable "Active". #. Click on "Add webhook" .. figure:: /Images/webhook/github/webhook-add.png :width: 932 #. Webhook was added GitHub should show a notice that creation of webhook was successful. .. figure:: /Images/webhook/github/webhook-added.png :width: 932 #. Trigger webhook and visit to check request Visit `intercept.typo3.com `_ and check "Recent actions" (scroll down). The repository should have created a "Docs hook ping from github repository". For the documentation to be rendered, the hook needs to be triggered: Either push to the branch ``main``. Or push to a new branch ``documentation-draft``. .. figure:: /Images/webhook/github/intercept-feedback.png :width: 932 .. index:: Webhooks; Bitbucket .. _webhook-bitbucket-cloud: Bitbucket cloud =============== Add auto rendering for a repository via Bitbucket webhook in five steps: .. rst-class:: bignums-xxl #. Go to "Settings" section within the repository .. figure:: /Images/webhook/bitbucket/cloud/repository-start.png :width: 932 #. Go to "Webhooks" section within the repository settings .. figure:: /Images/webhook/bitbucket/cloud/settings-tab.png :width: 932 #. Add webhook .. figure:: /Images/webhook/bitbucket/cloud/webhook-section.png :width: 932 #. Fill in webhook configuration #. Choose a title for this hook: for example "TYPO3 Docs". #. Fill URL field with :samp:`https://docs-hook.typo3.org`. #. Enable "Active" Status. #. Select ``Repository push`` for "Triggers". #. Click on "Save" .. figure:: /Images/webhook/bitbucket/cloud/webhook-add.png :width: 932 #. Webhook was added Bitbucket should show a notice, which disappears after some seconds, that creation of webhook was successful. Also the webhook should be shown in the list. .. figure:: /Images/webhook/bitbucket/cloud/webhook-added.png :width: 932 #. Trigger webhook and visit to check request Visit `intercept.typo3.com `_ and check "Recent actions" (scroll down). For the documentation to be rendered, the hook needs to be triggered: Either push to the branch ``main``. Or push to a new branch ``documentation-draft``. .. figure:: /Images/webhook/bitbucket/cloud/intercept-feedback.png :width: 932 .. index:: Webhooks; GitLab cloud Webhooks; GitLab self-hosted .. _webhook-gitlab: GitLab cloud and GitLab self-hosted =================================== Add auto rendering for a repository via GitLab webhook in four steps: .. rst-class:: bignums-xxl #. Go to "Integrations" section within the repository .. figure:: /Images/webhook/gitlab/repository-start.png :width: 932 #. Add webhook by filling in webhook configuration #. Fill URL field with :samp:`https://docs-hook.typo3.org`. #. Select ``Push events`` and ``Tag push events`` for "Trigger". #. Click on "Add webhook" .. figure:: /Images/webhook/gitlab/webhook-add.png :width: 932 #. Webhook was added The webhook should be shown in the list (scroll down). .. figure:: /Images/webhook/gitlab/webhook-added.png :width: 932 #. Trigger webhook and visit to check request Visit `intercept.typo3.com `_ and check "Recent actions" (scroll down). For the documentation to be rendered, the hook needs to be triggered: Either push to the branch ``main``. Or push to a new branch ``documentation-draft``. .. figure:: /Images/webhook/gitlab/intercept-feedback.png :width: 932