AWX webhooks launch job templates. A project has nothing of the kind, so keeping the local copy in step with the repository means a sync schedule that polls, or Update Revision on Launch and a fetch on every single job launch. Ascender projects take a webhook of their own, and a push updates the project as it lands.
Turning it on
The project form has Enable Webhook, the same workflow as a job template: pick the service, save, then copy the generated URL and key into the repository. GitHub, GitLab and Bitbucket Data Center are the three services.
Only a push starts a sync: GitHub push, GitLab Push Hook and Tag Push Hook, Bitbucket Data Center repo:refs_changed and mirror:repo_synchronized. Anything else the repository sends is acknowledged with a 200 and ignored, so an existing hook can be pointed at it without trimming its event list first.
What runs is the Sync button, not a checkout of whatever was pushed. The update honours the project's configured branch and refspec exactly as it always has.
Only the refs you care about
Webhook Ref Filter takes an fnmatch pattern, refs/heads/main or refs/heads/release-*, and only pushes to a matching ref sync the project. Left empty, which is the default, any push syncs it.
Duplicate deliveries are dropped the way they already are for job templates. The project update records the service and the delivery id, and a redelivery of an id that has been seen does nothing.
Bringing your own key
The webhook key used to be generated by the server and only by the server, which does not survive managing the controller as code: re-applying the resource rotates the key, and someone has to go and update the repository by hand. The key is writable now, write only, on projects, job templates and workflow job templates alike.
- Supply a key and it is kept as it is, so one secret in a vault can be applied to both sides by automation.
- Leave it blank and nothing changes: a key is generated when the service is set or changed.
- Blank the key of an active webhook and a fresh one is generated.
- Reading it still goes through the
webhook_key endpoint and its permission check, and a copy gets its own.
Two rules worth knowing
A manual project cannot enable a webhook, since there is no repository to push to, and a key cannot be set without a service. Projects take no webhook credential either: a sync has no status to post back.
This is @fernandorocagonzalez's, in #563.
The three services are the ones the receivers understand today. If you are hosting somewhere else, say which and what it sends on a push, and that is the start of a case for adding it.
