Submit pull request from GitHub App with single file permissions

Hi everyone!

For context, we have a GitHub App with the following permissions:

  • Read/write on pull requests.
  • Read/write on a single file foo.
  • No permissions on “contents” otherwise.

We’d like to open a pull request on the repository with the initial import of file foo for which we have permissions. However, I’m stuck on the issue that creating a pull request requires a head branch “in the same network” (as the docs puts it).

I do realize I have the permissions to write that file directly, but I don’t see a commit on the default branch as a pleasant user experience. However, I’m not seeing a way that wouldn’t require either the permissions to fork, or the permissions to create a branch.

I’m interested in any workaround you may think of!
Thank you for the help.

You’re absolutely right that changing files on the main branch is problematic – especially if protection rules are in place. As a GitHub App user I would be very nervous about an app that requested permissions to fork my repository, as it is effectively permission to exfiltrate.

If you look at Dependabot as an example, the approach it takes is to create a branch with the changes within the repository, e.g: Bump ws from 7.2.3 to 7.4.6, and then creates a Pull Request. Therefore, it’s quite well established that branch creation in the target repository (and the permissions required to do that) is the right approach :slight_smile:

Thank you for that answer! You’re right that Dependabot is a great example. The only problem, unless I’m missing something, is that creating a branch requires “Contents” permissions, which is quite a big deal, and defeats the purpose of requesting access to a single file in the first place :slight_smile:

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 read or 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 main branch.

That’s exactly what I was going for.

Thanks a lot for your help! Really appreciate :slight_smile: