fluidtypo3 / fluidtypo3-gizzle
Gizzle plugins for running various tasks for the FluidTYPO3 repositories
Requires
- namelesscoder/gizzle: @stable
- namelesscoder/gizzle-git-plugins: @stable
- namelesscoder/gizzle-typo3-plugins: @stable
Requires (Dev)
This package is auto-updated.
Last update: 2024-10-12 03:44:56 UTC
README
Official Fluid Powered TYPO3 Gizzle implementation
What is this?
Gizzle is a light-weight GitHub webhook listener written by Claus Due. In as few words as possible, Gizzle listens to requests from GitHub when activity occurs in your repositories. This package is an implementation of Gizzle in a composer project - and contains a few key plugins which provide integration with commits, pull requests and the TYPO3 extension repository.
The following plugins are included:
FormalitiesPlugin
which will analyse commits; validating the coding style of.php
files using CodeSniffer and the FluidTYPO3 rule set, and validating that commit messages conform to the TYPO3 standards regarding prefix, casing etc.SiteDeployPlugin
which, unsurprisingly, deploys repositories (in the case of Fluid Powered TYPO3 extensions, each of the three main branches are deployed to individual sites and for master, to fluidtypo3.org itself).
In addition the package utilises:
ExtensionReleasePlugin
from the gizzle-typo3-plugins set of plugins which we utilise to trigger automatic uploads to the TYPO3 extension repository when a new git tag is created in a repository that is a TYPO3 extension.
Together, these plugins form a near-realtime feedback system for pull requests (which even comments on each individual line if CGL was violated with a note about the nature of the violation), which sets a status indicator on pull requests' HEAD commit which GitHub will display in the pull request on GitHub; as well as an automatic release system which behaves like Packagist in that it uses tags to detect new versions - but then releases to TER instead.
Sister implementation
The fluidtypo3-gizzle
implementation of Gizzle has a sister project, fluidtypo3-development
, aimed at assisting local development in repositories that are TYPO3 extensions and which follow Fluid Powered TYPO3 coding style and rules. fluidtypo3-development
carries with it a range of command line utilities that either validate or manipulate the code in the repository; for example updating the version number consistently in both composer.json
and ext_emconf.php
files and manually uploading new versions to TER (an action which fluidtypo3-gizzle
automates). It will also install hooks for the git command which validate commit messages and runs coding style validation and unit tests before files are allowed to be committed. In fact, fluidtypo3-gizzle
utilises fluidtypo3-development
for some features and for the continuous integration that is used in the official repository.
So where fluidtypo3-gizzle
can validate the stuff that goes on via GitHub, fluidtypo3-development
can validate it before it reaches GitHub.
Using both in combination should ensure a minimum of human involvement in reviewing pull requests and a minimum of frustration for contributors because with fluidtypo3-development
they'll be warned in advance if they're about to commit incorrect code - and they'll be warned even if they use GitHub's web interface to create the commits that become the pull request (but unfortunately, not until it actually becomes a pull request).
Do-it-yourself instructions
The following instructions teach you how to fork, install and if necessary adapt fluidtypo3-gizzle
to do the exact same thing for your own repositories.
Installing files and HTTPD vhost
First of all, fork the repository so that you can commit and push any changes you need to make and preserve them in your own repository. Then, clone your forked repository to your web server:
git clone https://github.com/YOURNAME/fluidtypo3-gizzle.git
Then switch into this directory and run Composer's install:
cd fluidtypo3-gizzle
composer install --no-dev
If you intend to develop, we suggest removing the --no-dev
to get phpunit and other utilities installed. If installed without --no-dev
this package will add a new command that you can call once and enable the local development assistant described above:
./vendor/bin/make
Calling this command once is enough - after that, it will automatically be called before each commit you make, triggering code style validation and unit testing.
Lastly, create a virtual host that points to the web
folder inside the project (find the appropriate instructions for your HTTPD of choice). Optionally you can set the Apache DirectoryIndex
or corresponding option in another HTTPD to serve the github-webhook.php
file as default, which lets you shorten your URLs that you use for GitHub web hooks.
Preparing credentials
Gizzle requires at least a so-called secret
file which contains a secret you use when installing your web hook URLs in GitHub. You can choose this secret now and remember it when you create each web hook. Create the file in your project root directory:
echo "mysecretphrase" > .secret
In all web hooks you add on GitHub a dedicated input field is there for your secret
- enter the same secret
you placed in this file, in all web hooks you create (and which are received by this host, of course).
DON'T commit these files to your repository! Add them to .gitignore instead.
Depending on which of the plugins you expect to use you will also require one or both of the following:
GitHub personal access token
Personal Access Tokens can be generated via your account settings on GitHub and once generated, allows applications such as Gizzle to use GitHub as if it were using your account. The Personal Access Token is required for fluidtypo3-gizzle
to be able to use the FormalitiesPlugin
because it can comment on files in commits; and it is required for the updating of status on pull requests.
When creating your Personal Access Token you decide which privileges it should have. The absolute minimum requirements for use with fluidtypo3-gizzle
is the "public repos" and "comment" permissions; plus whichever permissions you plan to use if you plan to create your own Gizzle plugins.
If you decide to use a Personal Access Token, add it to your project root directory once you've created it and given it privileges:
echo "1234567890abcdef1234567890abcdef" > .token
Protect your Personal Access Token with the same care you would your GitHub login and password. DON'T commit these files to your repository!
TYPO3 credentials
In order to enable automatic uploads of repositories to the TYPO3 extension repository when new git tags are made, fluidtypo3-gizzle
requires a .typo3credentials
file which contains both username and password in clear text:
echo "username:password" > .typo3credentials
Protect your credentials. Make sure only people you trust have access to it! DON'T commit these files to your repository!
Installing web hooks in repositories
Once you have prepared the credentials, Gizzle will be able to validate the request coming from GitHub and ensure you won't receive requests from any other source.
The first repository to which you should add a hook is in your fork of fluidtypo3-gizzle
. The web hook you add here should be running the SelfUpdate.yml
settings file which basically 1) pulls changes from the remote tracked branch and 2) runs composer install, in the project itself. This allows you to push changes to your fork and have them deployed immediately. To add this web hook, edit the settings of your repository and in the "Web services and hooks" category, choose to create a new web hook. In the URL field, enter your virtual host's public URL and reference a settings file:
http://mydomain.com/github-webhook.php?settings=settings/SelfUpdate.yml
...and select to have it send you "just the push event".
You can test the hook to confirm that at least your secret
file is working but test requests will not trigger anything.
Then, in each of the repositories that you wish to mark for automatic validation of coding style using ours or your own rule set, add another web hook and this time, reference the PullRequest.yml
settings file:
http://mydomain.com/github-webhook.php?settings=settings/PullRequest.yml
But for this hook make sure it only receives the "pull request" event! Once added, this web hook will listen for new pull requests and changes to existing pull requests and when those occur, catch the files and commits that are being touched and validate them according to configured rules.
The final manifest that is provided by fluitypo3-gizzle
is the ExtensionRelease.yml
settings file. Referencing this file allows you to capture only the events that tag new releases:
http://mydomain.com/github-webhook.php?settings=settings/ExtensionRelease.yml
And for this hook, make sure it receives "just the push event". This means that the listener receives an event whenever any type of commit - not just tags - are created, but the plugin filters these out but only recognising "refs" which begin with the special heads/tags/
prefix.
On a final note: you can dispatch more than one settings manifest in each web hook:
http://mydomain.com/github-webhook.php?settings[]=settings/Manifest1.yml&settings[]=settings/Manifest2.yml
Note that the settings
parameter is turned into an array; any number of manifests can be added here (as long as the resulting URL is still of valid length). However: be careful when combining settings manifests this way - make sure that all the plugins which are involved actually match the event type or you will quickly find yourself with a bunch of events added and many redundant events, with many HTTP unnecessary requests to your web hook listener as a result.
Settings manifests and plugin references
Each of the manifest .yml
files inside the settings
directory consist of one ore more configurations of plugins that should be executed, along with parameters for the execution. To learn more about how such manifests can be created take a look in the official Gizzle reference about configuration.
The parameters supported by each of the plugins are documented in the repositories to which the plugin belongs; with the exception of the SiteDeploy
and Formalities
plugins which are tailored to Fluid Powered TYPO3 extensions and thus support only the parameters that are already defined in the settings file, nothing more, nothing less.
The plugins and libraries involved are located in the following repositories:
- https://github.com/NamelessCoder/gizzle-git-plugins which is used to trigger standard git commands through a manifest.
- https://github.com/NamelessCoder/gizzle-typo3-plugins which is used for the extension release logic.
- https://github.com/NamelessCoder/typo3-repository-client which carries the actual extension upload logic - and has CLI commands you can use for the same purpose.
- https://github.com/FluidTYPO3/fluidtypo3-gizzle which is the upstream of this project and any forks hereof.