From 264acd0de81ec8855bb7bb9e78a8712ca7abf4a6 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Mon, 3 Aug 2026 22:41:24 +0200 Subject: [PATCH] [TASK] Document Forgejo and Gitea webhook support Intercept gained support for Forgejo and Gitea push webhooks, so those hosts no longer need a mirror on another platform. Self-hosted instances work on any domain, the domain is approved once by the Documentation Team along with the repository. Add a setup section for them next to the existing ones, extend the list of supported hosts and rewrite the "Foreign setups" paragraph, which until now told those users to build a mirror. Two enumerations elsewhere named the supported hosts individually and would have gone stale again with the next host. They now link to the webhook page instead. One of them, in the rendering chapter, was already incomplete, it omitted Bitbucket. The new section has no screenshots yet, unlike its siblings. Signed-off-by: Sebastian Mendel --- Documentation/Howto/RenderingDocs/Index.rst | 3 +- .../Howto/WritingDocForExtension/FAQ.rst | 3 +- .../Howto/WritingDocForExtension/Index.rst | 3 +- .../Howto/WritingDocForExtension/Webhook.rst | 54 +++++++++++++++++-- 4 files changed, 57 insertions(+), 6 deletions(-) diff --git a/Documentation/Howto/RenderingDocs/Index.rst b/Documentation/Howto/RenderingDocs/Index.rst index 3e9f080b..829d9bc9 100644 --- a/Documentation/Howto/RenderingDocs/Index.rst +++ b/Documentation/Howto/RenderingDocs/Index.rst @@ -69,7 +69,8 @@ called :file:`Documentation` with a :file:`Documentation/Index.rst` and a :file:`Documentation/guides.xml` or a :file:`README.rst` / :file:`README.md` in the extension's root directory. -The extension has to be publicly available on GitHub or GitLab. You have to +The extension has to be publicly available on one of the +:ref:`supported repository hosts `. You have to establish a :ref:`Webhook ` and the Documentation Team has to :ref:`approve ` your first rendering. diff --git a/Documentation/Howto/WritingDocForExtension/FAQ.rst b/Documentation/Howto/WritingDocForExtension/FAQ.rst index b2c952b6..da56a479 100644 --- a/Documentation/Howto/WritingDocForExtension/FAQ.rst +++ b/Documentation/Howto/WritingDocForExtension/FAQ.rst @@ -147,7 +147,8 @@ TER (https://extensions.typo3.org) are two separate, independent entities. In theory you could have the documentation in GitHub (for example) and the extension (code) somewhere else (or not in Git at all). You just -need to fire the webhook from GitHub/GitLab/Bitbucket to trigger the +need to fire the webhook from one of the +:ref:`supported repository hosts ` to trigger the documentation rendering. diff --git a/Documentation/Howto/WritingDocForExtension/Index.rst b/Documentation/Howto/WritingDocForExtension/Index.rst index fb1c0bb1..2c40e8c4 100644 --- a/Documentation/Howto/WritingDocForExtension/Index.rst +++ b/Documentation/Howto/WritingDocForExtension/Index.rst @@ -58,7 +58,8 @@ the chapter yourself. Make changes and try :ref:`rendering ` the new documentation. To publish your documentation to https://docs.typo3.org -a :ref:`webhook needs to be added ` on GitHub, Bitbucket or GitLab. +a :ref:`webhook needs to be added ` on GitHub, Bitbucket, GitLab, +Forgejo or Gitea. A member of the Documentation Team has to approve your new documentation guide for publishing. In case the Team has questions, please follow the thread generated for your extension in the `TYPO3 slack organization `_ diff --git a/Documentation/Howto/WritingDocForExtension/Webhook.rst b/Documentation/Howto/WritingDocForExtension/Webhook.rst index 72b49e62..a6e40112 100644 --- a/Documentation/Howto/WritingDocForExtension/Webhook.rst +++ b/Documentation/Howto/WritingDocForExtension/Webhook.rst @@ -15,6 +15,7 @@ and integrates with the following repository hosts: * :ref:`webhook-github` * :ref:`webhook-bitbucket-cloud` and Bitbucket self-hosted * :ref:`GitLab Cloud ` and :ref:`GitLab self-hosted ` +* :ref:`Forgejo and Gitea `, including self-hosted instances .. contents:: Table of Contents :local: @@ -48,9 +49,13 @@ Foreign setups ============== If your repository is hosted outside the supported platforms -(GitHub, GitLab, Bitbucket) or its structure differs from a typical TYPO3 -extension, you must create a mirror on a supported platform. Otherwise, -automatic rendering will not be possible. +(GitHub, GitLab, Bitbucket, Forgejo, Gitea) or its structure differs from a +typical TYPO3 extension, you must create a mirror on a supported platform. +Otherwise, automatic rendering will not be possible. + +Self-hosted instances are supported on any domain. The Documentation Team +approves the domain of your instance once, together with the repository +approval described above. .. _webhook-how-webhook-works: @@ -229,6 +234,49 @@ To set up a GitLab webhook: .. figure:: /_Images/webhook/gitlab/intercept-feedback.png :width: 932 +.. index:: Webhooks; Forgejo +.. _webhook-forgejo: + +Forgejo and Gitea +================= + +Forgejo and Gitea are supported on any domain, so a self-hosted instance +needs no mirror. To set up the webhook: + +.. rst-class:: bignums-xxl + +#. Open the repository **Settings** and go to the **Webhooks** section. + +#. Click **Add Webhook** and choose **Forgejo** (**Gitea** on a Gitea + instance). + +#. Configure the webhook: + + * **Target URL**: `https://docs-hook.typo3.org` + * **HTTP Method**: `POST` + * **POST Content Type**: `application/json` + * **Trigger On**: `Custom Events`, with **Push** selected + + Leave the branch filter at its default so that tags are delivered as + well. Select push events only. Other events, such as branch creation + or deletion, are rejected by the endpoint and clutter the delivery + history of your webhook. + + Click **Add Webhook**. + +#. Test the webhook. + + Push a commit that changes `README.rst`, `README.md` or a file below + :file:`Documentation/` to `main` or `documentation-draft`. Then visit + `intercept.typo3.com `_ + and check the **Recent actions** section. + + .. note:: + The **Test Delivery** button of Forgejo sends a push event that + contains no changed files. The delivery is reported as successful, + but no documentation is rendered by it. Only a real push with + documentation changes triggers the rendering. + .. _webhook-deliveries: Reading the webhook deliveries on GitHub