{"id":413,"date":"2015-10-17T10:30:26","date_gmt":"2015-10-17T10:30:26","guid":{"rendered":"http:\/\/www.audero.it\/blog\/?p=413"},"modified":"2025-05-04T22:08:16","modified_gmt":"2025-05-04T22:08:16","slug":"upload-files-on-github-using-github-js","status":"publish","type":"post","link":"https:\/\/www.audero.it\/blog\/2015\/10\/17\/upload-files-on-github-using-github-js\/","title":{"rendered":"Upload files on GitHub using Github.js"},"content":{"rendered":"

For a few months now, I have been working on a project that employs the GitHub APIs<\/a>. The application I’m\u00a0building is completely client-side and provides a feature to upload files to a repository on GitHub. To simplify the\u00a0interaction with the API, I’m\u00a0using a library called Github.js<\/a>.<\/p>\n

Developing this feature has not been\u00a0straightforward since\u00a0the documentation of the library lacks examples of this type, or even mention if it’s possible at all. Moreover, I\u00a0wasn’t able to find any example on the web. Apparently, this functionality\u00a0is of interest for many people as demonstrated by this question on StackOverflow<\/a> and this issue opened on the Github.js’ repository<\/a>. With a bit of study of the library’s source I was eventually\u00a0able to develop\u00a0the functionality, so I thought to write a post to share my experience and the solution I came up with.
\n
\nIn this article, I’ll explain how to upload any file on a repository on GitHub using Github.js and discuss a couple of major issues you might face. If you want to see (a better version of) the code developed for this article in action, you can browse and download it from the repository I’ve created on GitHub<\/a>.<\/p>\n

\"github<\/p>\n

Saving text-based files with Github.js<\/h2>\n

Github.js<\/a> exposes different methods that make the\u00a0interaction with the GitHub API easier. To save a text-based file on GitHub, such as Markdown or HTML, the code needed is quite short and simple.<\/p>\n

To start, you have to download and include Github.js in your project. Once done, you create a new instance of the Github<\/code> object exposed by the library and create an object representing the repository you want to work with. Finally, you create a new file on the repository (or update it if the file already exists) with the content you want using a method of the library called write()<\/code>. In the Git parlance, creating or updating a file means commit<\/em>. Therefore, you also need to specify a commit message.<\/p>\n

The code that implements these steps should look like the following snippet:<\/p>\n

\n\/\/ Creates a new instance of the Github object exposed by Github.js\nvar github = new Github({\n  username: 'YOUR_USERNAME',\n  password: 'YOUR_PASSWORD',\n  auth: 'basic'\n});\n\n\/\/ Creates an object representing the repository you want to work with\nvar repository = github.getRepo('A_USERNAME', 'A_REPOSITORY_NAME');\n\n\/\/ Creates a new file (or updates it if the file already exists)\n\/\/ with the content provided\nrepository.write(\n   'BRANCH_NAME', \/\/ e.g. 'master'\n   'path\/to\/file', \/\/ e.g. 'blog\/index.md'\n   'THE_CONTENT', \/\/ e.g. 'Hello world, this is my new content'\n   'YOUR_COMMIT_MESSAGE', \/\/ e.g. 'Created new index'\n   function(err) {}\n);\n<\/pre>\n
At the moment, it isn’t possible to create or update more than one file with one commit using the GitHub API, thus using Github.js. So, every time you call the write()<\/code> method, a new commit will be created.<\/p>\n
The GitHub API accepts data that represent the content of the file in Base64<\/a>. In the previous example I was able to provide a simple string because when write()<\/code> Github.js converts it into the appropriate format (Base64)\u00a0using the window.btoa()<\/a> method.\u00a0As you’ll learn in the remainder of the article, this feature will turn into an issue when dealing with non text-based files, but this won’t be a problem with the solution I’ll explain.<\/p>\n
Uploading files with Github.js<\/h2>\n
To let your web application upload files on GitHub with Github.js, you need a way to select these files. Luckily, HTML has a native element designed for this purpose:<\/p>\n
\n&amp;lt;input type=&amp;quot;file&amp;quot; \/&amp;gt;\n<\/pre>\n
In case you need to upload more than one file, you can use the multiple<\/code> attribute as shown below:<\/p>\n
\n&amp;lt;input type=&amp;quot;file&amp;quot; multiple \/&amp;gt;\n<\/pre>\n
With this element in place, you’re able to select one or more files but nothing more than that happens. So, you have to write the code that reads the content of the selected files and upload them on GitHub. Let’s start with the first task.<\/p>\n
Reading files with JavaScript<\/h3>\n
The first task can be achieved by employing FileReader<\/code><\/a> and its readAsDataURL()<\/code> method<\/a>. readAsDataURL()<\/code> accepts a Blob<\/code> or a File<\/code> object and gives you the content as a Base64 encoded string. In the previous sentence I’ve used the word gives<\/em> instead of return<\/em> on purpose. In fact, the method itself doesn’t return the content\u00a0(it returns undefined<\/code>) because the read operation is asynchronous. To retrieve the content you have to listen for the loadend<\/code> event which\u00a0is fired when the read operation is completed.<\/p>\n
To better understand how this mechanism works, let’s create a function called readFile()<\/code> that accepts a File<\/code> instance and reads its content. To avoid the issue known as callback hell<\/a>, the function will return a Promise<\/a>. If you need a primer on Promises, I suggest you to read the article JavaScript Promises, There and back again<\/cite><\/a> by Jake Archibald<\/a><\/cite>.<\/p>\n
The readFile()<\/code> function resolves the Promise if the read is successful or reject it if an error occurs. When the Promise is resolved, the function provides an object with\u00a0two properties: filename<\/code> and content<\/code>. The former specifies the name of the file. The latter defines the binary representation of the file’s content, with the information about its mime type and its\u00a0encoding removed. You may wonder why the content is binary encoded if readAsDataURL()<\/code> returns the string in Base64. The reason is that we have to convert it to a binary encoding, using the window.atob()<\/code><\/a> method, to compensate the opposite conversion that Github.js does on our behalf when calling\u00a0write()<\/code>. If you don’t do that, Github.js will send to the GitHub API a string that is double encoded in Base64 (i.e. Github.js encodes in Base64 a string that is already in Base64). As a result, if you try to open the file in your browser via the GitHub web interface or download it, you will receive an error because the file isn’t encoded correctly.<\/p>\n
The code that implements the above description is shown below:<\/p>\n
\nfunction readFile(file) {\n   return new Promise(function (resolve, reject) {\n      var fileReader = new FileReader();\n\n      fileReader.addEventListener('load', function (event) {\n         var content = event.target.result;\n\n         \/\/ Strip out the information about the mime type of the file and the encoding\n         \/\/ at the beginning of the file (e.g. data:image\/gif;base64,).\n         content = atob(content.replace(\/^(.+,)\/, ''));\n\n         resolve({\n            filename: file.name,\n            content: content\n         });\n      });\n\n      fileReader.addEventListener('error', function (error) {\n         reject(error);\n      });\n\n      fileReader.readAsDataURL(file);\n   });\n}\n<\/pre>\n
The readFile()<\/code> function enables us to read one or more files, so we are now ready to upload them. But before discussing how to do that, we have to create a support function to overcome an issue of the GitHub API. Let’s learn more.<\/p>\n
Promisifying Github.js<\/h3>\n
The application I’m working on requires to upload one or more files at a time, no matter how many commits are created. In my first attempts, I thought to speed up the process by executing all the calls to write()<\/code>, one for each file, in parallel. However, the process was always failing with a weird error message. While doing a bit of research to understand what the cause could be, I stumbled upon this question on StackOverflow<\/a>, and specifically this comment<\/a>:<\/p>\n
I’m guessing you’re hitting a corner case with the API due to these sequential writes that are happening one after another. Can you please try putting a sleep in your script so that you wait for a second or two between calls? That should resolve the issue. We’re working on fixing this on our end, but I can’t make any Promises about when this will be resolved. Let me know if that doesn’t help.<\/p><\/blockquote>\n
Now, having a sleep in between the calls was a no go for me. So, I decided to promisify the write()<\/code> method so that I could execute all the calls in sequence without having to resort to any sleep approach. This decision turned out to be a winner.<\/p>\n
The function to promisify write()<\/code> is reported below:<\/p>\n
\nfunction saveFile(data) {\n   return new Promise(function(resolve, reject) {\n      data.repository.write(\n         data.branchName,\n         data.filename,\n         data.content,\n         data.commitTitle,\n         function(err) {\n            if (err) {\n               reject(err);\n            } else {\n               resolve(data.repository);\n            }\n         }\n      );\n   });\n}\n<\/pre>\n
With this code in place, I can introduce you to the last function needed.<\/p>\n
Uploading files<\/h3>\n
To complete the feature we’re discussing, all we need is a function that accepts an array (or array-like object) of files to read and a commit message. I’ll call such function uploadFiles()<\/code>. It’ll return a Promise that is resolved when all the files have been uploaded correctly or rejected in case of error. The body of the function is short but terse, and might be a bit complicated to understand. So, before showing the code let’s discuss it in depth.<\/p>\n
The first operation to perform is to read all the files provided and store the resulting Promises into an array. The read operations are executed in parallel to improve the application’s performance. To complete this step we’ll use the readFile()<\/code> function discussed earlier and map()<\/code><\/a>. To move to the next step, we have to wait until the read of all the files is completed. To achieve this goal, we’ll employ Promise.all()<\/code><\/a> and pass to it the array of Promises we created.<\/p>\n
Once all the Promises are resolved, the function can start sending the data to GitHub using saveFile()<\/code>. As I mentioned before, unfortunately the requests must be sent in sequence and we can’t upload all the files at once with a single commit. This means that a new request has to start when the previous one is resolved. For this reason, we have to create a chain of then()<\/code> calls. In addition, for each call to then()<\/code>, a new commit will be created. The are many ways we can achieve this goal, the simplest of which is to use a for<\/code> loop or a similar construct. Personally, I preferred to use a functional approach that employs reduce()<\/code><\/a>. The chain of Promises created is the returned value of the function.<\/p>\n
The code of the uploadFiles()<\/code> function is listed below:<\/p>\n
\nfunction uploadFiles(files, commitTitle) {\n   \/\/ Creates an array of Promises resolved when the content\n   \/\/ of the file provided is read successfully.\n   var filesPromises = [].map.call(files, readFile);\n\n   return Promise\n      .all(filesPromises)\n      .then(function(files) {\n         return files.reduce(\n            function(promise, file) {\n               return promise.then(function() {\n                  \/\/ Upload the file on GitHub\n                  return gitHub.saveFile({\n                     repository: gitHub.repository,\n                     branchName: config.branchName,\n                     filename: file.filename,\n                     content: file.content,\n                     commitTitle: commitTitle\n                  });\n               });\n            },\n            Promise.resolve()\n         );\n      });\n}\n<\/pre>\n
The caller of uploadFiles()<\/code> can use the returned Promise to show a successful message to the user once the whole process is completed, or an error message if an issue occurs at any stage. An example is shown below:<\/p>\n
\nvar files = document.getElementById('file').files;\nvar commitTitle = 'Files uploaded';\n\nuploadFiles(files, commitTitle)\n   .then(function() {\n      alert('Your file has been saved correctly.');\n   })\n   .catch(function(err) {\n      console.error(err);\n      alert('Something went wrong. Please, try again.');\n   });\n<\/pre>\n
Done! You’re now ready to upload as many files as you want on GitHub via its API using Github.js.<\/p>\n
Conclusions<\/h2>\n
In this tutorial I’ve explained how to use Github.js to upload files on GitHub via its APIs. Finding the solution to this problem wasn’t straightforward and I had to dig into the library’s source to fully understand what was going on. Overall it has been a good experience that let me understand a couple of important issues to take into account. Specifically, I learned that behind the scene Github.js converts a string into its Base64 equivalent using the window.btoa()<\/a> method. I also learned that the GitHub API doesn’t allow you to create or save multiple files with one commit, and that it has an issue with sequential writes that happens quickly one after another.<\/p>\n
If you want to see (a better version of) the code developed for this article in action, you can browse and download it from the repository I’ve created on GitHub<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
For a few months now, I have been working on a project that employs the GitHub APIs<\/a>. The application I’m\u00a0building is completely client-side and provides a feature to upload files to a repository on GitHub. To simplify the\u00a0interaction with the API, I’m\u00a0using a library called Github.js<\/a>.<\/p>\n
In this article, I’ll explain how to upload any file on a repository on GitHub using Github.js and discuss a couple of major issues you might face. If you want to see (a better version of) the code developed for this article in action, you can browse and download it from the repository I’ve created on GitHub<\/a>.<\/p>\n","protected":false},"author":1,"featured_media":495,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[3],"tags":[52,51,54,53,46,11],"class_list":["post-413","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-javascript","tag-api","tag-github","tag-github-api","tag-github-js","tag-javascript","tag-web"],"jetpack_featured_media_url":"https:\/\/www.audero.it\/blog\/wp-content\/uploads\/2016\/06\/github-octocat-logo.png","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p9Or4e-6F","jetpack-related-posts":[{"id":339,"url":"https:\/\/www.audero.it\/blog\/2014\/10\/18\/state-web-notifications-api\/","url_meta":{"origin":413,"position":0},"title":"The State of the Web Notifications API","author":"Aurelio De Rosa","date":"October 18, 2014","format":false,"excerpt":"Today I was reviewing my HTML5 API demos repository to keep its information updated and relevant. In the last two weeks Google has released\u00a0Chrome 38, Opera has released Opera 25, and Mozilla has released Firefox 33.\u00a0Every time a new version of a browser is available, it may\u00a0introduce support for new\u2026","rel":"","context":"In "JavaScript"","block_context":{"text":"JavaScript","link":"https:\/\/www.audero.it\/blog\/category\/javascript\/"},"img":{"alt_text":"push notifications","src":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/10\/push-notifications.jpg?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/10\/push-notifications.jpg?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/10\/push-notifications.jpg?resize=525%2C300&ssl=1 1.5x"},"classes":[]},{"id":672,"url":"https:\/\/www.audero.it\/blog\/2017\/01\/18\/from-javascript-developer-to-javascript-engineer-find-all-celebrities-in-a-set-of-people\/","url_meta":{"origin":413,"position":1},"title":"From JavaScript developer to JavaScript engineer: find all celebrities in a set of people","author":"Aurelio De Rosa","date":"January 18, 2017","format":false,"excerpt":"In the first article of my series From JavaScript developer to JavaScript engineer titled From JavaScript developer to JavaScript engineer: Re-implementing ECMAScript 2015's String.prototype.repeat() method I've discussed how computer science concepts can help in writing better and more elegant software. Specifically, I've demonstrated how to use appropriate algorithms and data\u2026","rel":"","context":"In "From JavaScript developer to JavaScript engineer"","block_context":{"text":"From JavaScript developer to JavaScript engineer","link":"https:\/\/www.audero.it\/blog\/category\/javascript\/from-javascript-developer-to-javascript-engineer\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2016\/12\/oscars-2014-selfie.jpg?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2016\/12\/oscars-2014-selfie.jpg?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2016\/12\/oscars-2014-selfie.jpg?resize=525%2C300&ssl=1 1.5x"},"classes":[]},{"id":637,"url":"https:\/\/www.audero.it\/blog\/2016\/12\/16\/from-javascript-developer-to-javascript-engineer-re-implementing-ecmascript-2015s-string-prototype-repeat-method\/","url_meta":{"origin":413,"position":2},"title":"From JavaScript developer to JavaScript engineer: re-implementing ECMAScript 2015’s String.prototype.repeat() method","author":"Aurelio De Rosa","date":"December 16, 2016","format":false,"excerpt":"As developers, our work is to solve problems which often implies writing code. Some of the problems we face look really simple in nature, but their simplicity leads us to write sub-optimal solutions without even realizing it. JavaScript developers come from very different backgrounds, and assuming that everyone has the\u2026","rel":"","context":"In "From JavaScript developer to JavaScript engineer"","block_context":{"text":"From JavaScript developer to JavaScript engineer","link":"https:\/\/www.audero.it\/blog\/category\/javascript\/from-javascript-developer-to-javascript-engineer\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2016\/12\/time-complexity-comparison.png?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2016\/12\/time-complexity-comparison.png?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2016\/12\/time-complexity-comparison.png?resize=525%2C300&ssl=1 1.5x"},"classes":[]},{"id":404,"url":"https:\/\/www.audero.it\/blog\/2015\/07\/14\/trick-of-the-day-css-scroll-snap-points\/","url_meta":{"origin":413,"position":3},"title":"Trick of the day: CSS Scroll Snap Points","author":"Aurelio De Rosa","date":"July 14, 2015","format":false,"excerpt":"When you create a gallery, you usually want to implement a feature where every time the user clicks (or press the ENTER key) on an arrow, you move straight to the next (or previous) image. This effect can also be used to create a website that has several sections, each\u2026","rel":"","context":"In "Trick of the day"","block_context":{"text":"Trick of the day","link":"https:\/\/www.audero.it\/blog\/category\/trick-of-the-day\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2015\/07\/css-scroll-snap-points.png?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2015\/07\/css-scroll-snap-points.png?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2015\/07\/css-scroll-snap-points.png?resize=525%2C300&ssl=1 1.5x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2015\/07\/css-scroll-snap-points.png?resize=700%2C400&ssl=1 2x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2015\/07\/css-scroll-snap-points.png?resize=1050%2C600&ssl=1 3x"},"classes":[]},{"id":329,"url":"https:\/\/www.audero.it\/blog\/2014\/09\/19\/resources-beginner-front-end-developers\/","url_meta":{"origin":413,"position":4},"title":"Resources for Beginner Front-end Developers","author":"Aurelio De Rosa","date":"September 19, 2014","format":false,"excerpt":"Few weeks ago I received an email from a developer asking me for suggestions on how to delve into the front-end world. After having replied to this email, I thought that it'd have been nice to share the same suggestions on my blog. That's exactly what you'll find in this\u2026","rel":"","context":"In "Discussions & Opinions"","block_context":{"text":"Discussions & Opinions","link":"https:\/\/www.audero.it\/blog\/category\/discussions-opinions\/"},"img":{"alt_text":"html5 css3 javascript logos","src":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/09\/front-end-stack.png?resize=350%2C200&ssl=1","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/09\/front-end-stack.png?resize=350%2C200&ssl=1 1x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/09\/front-end-stack.png?resize=525%2C300&ssl=1 1.5x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/09\/front-end-stack.png?resize=700%2C400&ssl=1 2x, https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2014\/09\/front-end-stack.png?resize=1050%2C600&ssl=1 3x"},"classes":[]},{"id":626,"url":"https:\/\/www.audero.it\/blog\/2016\/12\/05\/monkey-patching-javascript\/","url_meta":{"origin":413,"position":5},"title":"Monkey patching in JavaScript","author":"Aurelio De Rosa","date":"December 5, 2016","format":false,"excerpt":"When working on a project, we often use libraries that implement methods that aren't built-in in the programming language in use but we need. These libraries don't cover all the possible methods, so they might lack one or more crucial features we need. When this happens, we have two choices:\u2026","rel":"","context":"In "JavaScript"","block_context":{"text":"JavaScript","link":"https:\/\/www.audero.it\/blog\/category\/javascript\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/www.audero.it\/blog\/wp-content\/uploads\/2016\/12\/monkey-patching.png?resize=350%2C200&ssl=1","width":350,"height":200},"classes":[]}],"_links":{"self":[{"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/posts\/413","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/comments?post=413"}],"version-history":[{"count":44,"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/posts\/413\/revisions"}],"predecessor-version":[{"id":1056,"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/posts\/413\/revisions\/1056"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/media\/495"}],"wp:attachment":[{"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/media?parent=413"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/categories?post=413"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.audero.it\/blog\/wp-json\/wp\/v2\/tags?post=413"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}