Hm, you’re right, that’s a very good point – I didn’t realise that branch permissions were part of contents (which, in hindsight, makes sense).
Reviewing the documentation more carefully, the description of “single file” access is…
This is a narrowly-scoped permission that allows the app to access a single file in any repository. When you set the
single_file permission to
write , this field provides the path to the single file your GitHub App will manage. […]
My interpretation of that is that if your app requests write access to a single file, the expectation is that the file is owned by the app, and therefore, making changes to it on the default branch is correct.
I searched GitHub for uses of
single_file_name to better understand how it’s interpreted and used by others. There are no public examples of writing to the single file.
My conclusion is that writing to a single file is expected if the app owns the file, but in most cases – such as in-repository app configuration – the app doesn’t own the file, and therefore any change – whether it’s via a Pull Request, or directly to the main branch – is not expected behaviour.
Are you trying to build a pleasant onboarding experience (i.e: I install your app, you create a Pull Request with the default configuration?) or do you have a unique case where the app should own a specific file? Despite what I said in my earlier comment, I am now convinced that if the file is owned by the app (i.e: I would never change it, only the app would) then changes on the main branch are acceptable. If the file is not owned by the app (e.g: an app config file) then it should not be managed by the app (i.e: no writing, read only).
You could reach out to GitHub’s Marketplace team to find out if there are any examples of public apps that use the
single_file_name permission with writing, and then you could reach out to the app authors to understand what their users feeling is towards changes directly on the