Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/webhooks/webhook-events-and-payloads
What part(s) of the article would you like to see updated?
When receiving a push event in a GitHub app, you'll receive an object with top level installation property:
"installation":{"id":...,"node_id":...}
When receiving an installation/installation_repositories event you'll receive an object with top level installation property:
"installation":{"id":...,"client_id":...,"account":...,"repository_selection":...,"access_tokens_url":...,"repositories_url":...,"html_url":...,"app_id":...,"app_slug":...,"target_id":...,"target_type":...,"permissions":...,"events":...,"created_at":...,"updated_at":...,"single_file_name":null,"has_multiple_single_files":...,"single_file_paths":...,"suspended_by":...,"suspended_at":...}
Both are documented with the description: "Installation" and the generic type "object". The only property in common is "id" (side node, I'm surprised that "node_id" isn't common, probably an implementation thing not sending it 🤔)
I'd much appreciate it if some of the properties were given a little more description, for example the entire schema of the installation object and the circumstances/conditions where some properties might not be sent. The same can be said for the following properties in the docs:
"enterprise": object
"organization": object
"repository": object
"sender": object
Which are all generically typed as "object"
I haven't found anywhere that describes the shape of these objects and the inconsistency can make an app break without warning.
edit: I found the github api schema which is useful and in my opinion, should be linked by the docs in more places (in the webhook-events-and-payloads article for example). Alternatively, a brief note in that article should mention that one typing of Installation is not the same as another and to make no assumptions.
Additional information
No response
Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/webhooks/webhook-events-and-payloads
What part(s) of the article would you like to see updated?
When receiving a push event in a GitHub app, you'll receive an object with top level installation property:
"installation":{"id":...,"node_id":...}When receiving an installation/installation_repositories event you'll receive an object with top level installation property:
"installation":{"id":...,"client_id":...,"account":...,"repository_selection":...,"access_tokens_url":...,"repositories_url":...,"html_url":...,"app_id":...,"app_slug":...,"target_id":...,"target_type":...,"permissions":...,"events":...,"created_at":...,"updated_at":...,"single_file_name":null,"has_multiple_single_files":...,"single_file_paths":...,"suspended_by":...,"suspended_at":...}Both are documented with the description: "Installation" and the generic type "object". The only property in common is "id" (side node, I'm surprised that "node_id" isn't common, probably an implementation thing not sending it 🤔)
I'd much appreciate it if some of the properties were given a little more description, for example the entire schema of the installation object and the circumstances/conditions where some properties might not be sent. The same can be said for the following properties in the docs:
"enterprise": object
"organization": object
"repository": object
"sender": object
Which are all generically typed as "object"
I haven't found anywhere that describes the shape of these objects and the inconsistency can make an app break without warning.edit: I found the github api schema which is useful and in my opinion, should be linked by the docs in more places (in the webhook-events-and-payloads article for example). Alternatively, a brief note in that article should mention that one typing of
Installationis not the same as another and to make no assumptions.Additional information
No response