From 0f11a6818b65ef25babc31726879a8ed516aceeb 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 df7a3d9a..d3a672a7 100644 --- a/Documentation/Howto/RenderingDocs/Index.rst +++ b/Documentation/Howto/RenderingDocs/Index.rst @@ -67,7 +67,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 8a2a97a5..70f92fc3 100644 --- a/Documentation/Howto/WritingDocForExtension/FAQ.rst +++ b/Documentation/Howto/WritingDocForExtension/FAQ.rst @@ -133,7 +133,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 e49871da..4bc2f7a0 100644 --- a/Documentation/Howto/WritingDocForExtension/Index.rst +++ b/Documentation/Howto/WritingDocForExtension/Index.rst @@ -53,7 +53,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 92869c6a..8e831fa7 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-testing: Testing Webhooks