Webhook

This section describes how to add webhooks for auto rendering to a repository.

The system currently supports Git as VCS (Version Control System), and the following hosters:

If none of the above is used, a mirror to one of these is recommended. Also the Documentation Team can setup custom hostings.

The following sections provide illustrated walkthrough tutorials on how to add the necessary hook for the respective hoster.

Important

The first time a new repository triggers the webhook, the request will not be processed. Instead, the TYPO3 Documentation Team has to approve. This is necessary to prevent misuse of the infrastructure and extension names.

In case this takes too long, request the approval within the Slack channel #typo3-documentation. Registration for Slack is available at my.typo3.org.

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 master branch or documentation-draft branch can be used, see Supported branches.

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.

GitHub

Add auto rendering for a repository via GitHub webhook in five steps:

  1. Go to “Settings” tab within the repository

    ../_images/repository-start.png
  2. Go to “Webhooks” section within the repository settings

    ../_images/settings-tab.png
  3. Add webhook

    ../_images/webhook-section.png
  4. Fill in webhook configuration

    1. Configure URL https://docs-hook.typo3.org for field “Payload URL”.
    2. Select application/json as “Content type”.
    3. Enable “SSL verification”.
    4. Select Just the push event. for “Which events would you like to trigger this webhook?”.
    5. Enable “Active”.
    6. Click on “Add webhook”
    ../_images/webhook-add.png
  5. Webhook was added

    GitHub should show a notice that creation of webhook was successful.

    ../_images/webhook-added.png
  6. (Optional) visit intercept and check request

    If curious, 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 master. Or push to a new branch documentation-draft.

    ../_images/intercept-feedback.png

Bitbucket Cloud

Add auto rendering for a repository via Bitbucket webhook in five steps:

  1. Go to “Settings” section within the repository

    ../_images/repository-start1.png
  2. Go to “Webhooks” section within the repository settings

    ../_images/settings-tab1.png
  3. Add webhook

    ../_images/webhook-section1.png
  4. Fill in webhook configuration

    1. Choose a title for this hook: e.g. “TYPO3 Docs”.
    2. Fill URL field with https://docs-hook.typo3.org.
    3. Enable “Active” Status.
    4. Select Repository push for “Triggers”.
    5. Click on “Save”
    ../_images/webhook-add1.png
  5. 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.

    ../_images/webhook-added1.png
  6. (Optional) visit intercept and check request

    If curious, 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 master. Or push to a new branch documentation-draft.

    ../_images/intercept-feedback1.png

GitLab Cloud and GitLab Self-hosted

Add auto rendering for a repository via GitLab webhook in four steps:

  1. Go to “Integrations” section within the repository

    ../_images/repository-start2.png
  2. Add webhook by filling in webhook configuration

    1. Fill URL field with https://docs-hook.typo3.org.
    2. Select Push events and Tag push events for “Trigger”.
    3. Click on “Add webhook”
    ../_images/webhook-add2.png
  3. Webhook was added

    The webhook should be shown in the list (scroll down).

    ../_images/webhook-added2.png
  4. (Optional) Trigger webhook and visit intercept to check request

    If curious, 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 master. Or push to a new branch documentation-draft.

    ../_images/intercept-feedback2.png