GitHub Webhook Listener which releases TYPO3 extensions to TER when tags are created
This project allows any GitHub-hosted repository containing a TYPO3 CMS extension to be released to the official TYPO3 Extension Repository (hereafter referred to as TER) by adding a very simple GitHub web hook.
The official endpoint of this service is
but you are welcome to install this package on your own and use that
installation location as endpoint.
The project uses Gizzle to listen for GitHub events and uses Gizzle TYPO3 plugins to do the actual uploading. Internally, the Gizzle TYPO3 plugins use the TYPO3 Repository Client.
- A public GitHub repository containing your extension's source code.
- For custom endpoints only: access to the
phpCLI commands as well as some way to serve the
web/index.phpfile through HTTP/HTTPS.
- Edit the settings of your repository and locate "Webhooks & services".
- Click "Add webhook" to create a new hook.
- In "Payload URL", fill in the endpoint URL you wish to use. The default
- Add your unique credentials and information to the URL. There are two
possible URL formats:
- If your GitHub repository name is not the same as your TER extension
key, a URL like
https://release.namelesscoder.net/my_extension/user:password. must be used - which will release the repository as key
- If your GitHub repository is already named the same as your extension
key you can leave out that part of the URL and use a shorter URL like
- Alternatively, if you feel more comfortable with it and the endpoint
supports it, use
https://username:email@example.com/my_extension. This method only works if the server supports the
authnz_external_moduleor corresponding external authentications - see below.
- If your GitHub repository name is not the same as your TER extension key, a URL like
- Enter a "Secret". We use a fixed secret for now - enter the text
- Leave the "Which events..." selectors as-is. We only need the
Unfortunately there is no way to isolate an event that only gets dispatched
when you create new tags - which is why we have to listen to all
We simply ignore those that do not refer to a tag.
Because your credentials are included in the URL, we are doing the following on the default endpoint and you should definitely do the same if you create one:
- The URL is protected by SSL.
- The full URL of requests is never logged.
Please note that this credentials-in-URL approach is considered temporary and is only implemented because there currently are no other ways. The end goal is to use a token solution both for the "Secret" that is currently fixed, as well as for the credentials that must be passed to TER. The former will be solved by creating an official GitHub Service but the latter will depend on work that has to be done on TER or even TYPO3 SSO itself.
If your web server supports it (Apache does via
you can register an external authenticator (change/move the path if needed):
<IfModule authnz_external_module> DefineExternalAuth fake environment /var/www/release.namelesscoder.net/fake-auth.sh </IfModule>
...which goes in your virtual host or root server configuration. The
script is a dummy that allows any username and password to be authenticated -
and if done this way, this project will instead read those (fake) credentials.
This means you can specify the credentials to use when uploading to TER, as
To create a new TER release from your GitHub repository simply create a new tag and push it. The uploader will then use the message of the commit you tag as the upload comment on TER. To create and push a new tag:
git tag 1.2.3 git push origin 1.2.3
Which creates a new tag called
1.2.3 and pushes it to the remote called
The results of uploads triggered this way can be read in two different places:
- The publicly available message that the release was created gets added as a comment to the commit that was HEAD of the repository when tagging.
- The privately available debugging information can be viewed by locating the "Webhooks & services" panel as described in the installation section, and clicking the URL that was added. A short list of most recent transactions is displayed and clicking each one will allow you to read any technical errors.
The behavior of this plugin is very easily described:
- Whenever you push to GitHub, we receive an event.
- We analyse the Payload HEAD:
- If it is not a new tag we exit.
- If it is a new tag we upload a new release.
- We set a "success" status flag on the commit you tagged.
- We add a comment to the commit you tagged, saying it was released to TER.
- We assign a bit of debugging information and send our response to GitHub.
The whole process should only take a couple of seconds, depending on how large your extension is. If at any point during the process an error occurs, it is caught and can be inspected in the web hook response as described above.