Single file write access


We’ve heard some folk say they’d like their Integration be able to write a certain file, but don’t need write access to all the contents of a repository. If that’s something you’d be interested in, can you tell us a bit more about your use case? Is it a certain file type - JSON, markdown? A certain filename?


I was thinking about this yesterday. It sounds like it could be useful, but I wonder if it needs to be very flexible to actually being useful. I don’t see people adding a completely static file to their repositories, which makes me think that it cannot be as useful as it sounds.

From my use case, we have a configuration file called netlify.toml that people set in their repository roots’. The structure is the same, but the content, specially around build commands can be very different. This is a real example of that file:

  command = "npm run build"
  publish = "dist"

  command = "npm run build-preview"


This would be an incredibly useful feature for services that help users to maintain their countless configuration files.

With Greenkeeper I’m running such a service. It sends automated pull requests to update dependencies and monitors compatibility by creating branches and looking at the status API results. It only ever needs to read and write the package.json file. Not having to ask our users to grant us full access to their code would help us get our application approved by way more companies and as an integrator we can do way less warm if things go wrong.

In a dreamworld I could request access to just the files named package.json and get selective webhooks for when the content changes.

Huge +1 for this.



We just shipped the ability for an Integration to have access to a specific file only. You can choose read or read & write permission, and specify the path to the file your Integration needs to manage:

Docs on which API endpoints this gives access to:
Note: this will not give git access to the single file, only access via the API.

We don’t have a flow just yet for an existing Integration to change it’s default permissions, and allow anyone who has installed it to approve the change. This is available now for newly created Integrations to use. Let us know if that causes any problems for you, if your integration is only installed on your own account, we may be able to make changes there.

Look forward to your feedback :slight_smile:


Didn’t realize this thread existed, but this is 100% awesome and fits with the integration we’re building right now. I’m going to give it a shot within the next few days and let you know how it works out!

@keavy - had a chance to give this a shot this morning and haven’t been able to get it to work. I am receiving 403 errors:

{"message"=>"Resource not accessible by integration", "documentation_url"=>""}

My other integration that has full read/write access to the RepositoryContents:Push action successfully allows me to write/create a file using the /repos/:owner/:repo/contents/:path endpoint. Using the same code with an integration that only has access to the specific file path doesn’t seem to work. Not sure if I set things up incorrectly or if there’s something else going on.


@bkendzior, would you mind contacting us through with the specifics of your request - if you could include details of the Integration (id or name) and which repo and path you were requesting. Example curl -v output would be great. Then we can figure out if it’s a permissions issue or a bug. Thanks!


This is a great addition! Do you think that could be expanded to support multiple files? I guess it would get complex quite quickly, but we would need access to at least 2 files to support our use case.


Hi @theflow, we’re not planning on expanding the single file access to support multiple files, but always interested to hear more on use cases :slight_smile: Currently writing to multiple files would need write access to “contents” permission.


A use case for multiple files would be like guthub does for the pullrequest/issue templates. Look for a config file in the main repo folder or in a specific subfolder (.github/.config etc)


Hey there, I have a case for allowing either multiple files or a folder and it’s hierarchy as the single file permissions.

I build a project called Peril which uses github app events to trigger bot-like DSLs which handles a lot of work similar to probot. Whereas probot is config based, Peril only provides all the attributes and expects you you create rules based on them.

I had a request from an enterprise company to investigate the single file permissions as they don’t want the app to have access to code. You need to be able to access a JSON file for config, and a dangerfile.js per repo. I can just make it work with a bit of hacking (rename the JSON file to dangerfile.js) but hooking up to more than one event from the GitHub app would be infeasible without creating a really really long single file.

So ideally I’d like to be able to say: single file permissions: "peril/" and be able to have access to anything inside that subfolder in my github app.


We are importing one single file from repos into our application. We want to makes sure this file is up-to-date on our end.

Is it possible to provide a push web hook for the single file we have access to?


Thanks for the request @chengyin. I agree that it would make sense to have the relevant webhook activity for that file. I’ve created an internal issue to track this request, and we’ll report back if we have any more information.


Awesome. Thank you @jmilas!


@keavy Are there any plans to ship the “single file” feature to GitHub Enterprise?

/cc @jonico


I believe GitHub Apps were shipped to Enterprise in 2.12: Do you not see just that permission option?


Yeah, Apps were shipped with 2.12 but just that permission is missing :slight_smile:


:wave: @larsxschneider that permission should be there. I’m sorry it appears to be missing for you :thinking:.

I haven’t been able to reproduce a case where it wouldn’t show up in Enterprise. Would you mind sending over a screenshot of your setting page so we can see if anything else looks off? Is there anything else unique that you think might be a contributing factor?


@jmilas @keavy: You are right, I am wrong. The feature is there, I just overlooked it :slight_smile:
Thanks for taking the time to respond!