github-logo

Github Integration

Github Integration is a plugin that allows you to integrate a native GitHub client inside the Godot Engine Editor.

banner.png

I decided to develop this plugin with the intent to provide an intuitive and easy to use tool, both for experts and novice programmers, directly inside the engine with which we are developing the project, creating a closed and functional box.

  1. Problem

  2. Main Features

  3. Design and Functioning

  4. Installation and Usage

Problem

This plugin is not intended to be a complete replacement of the browser client, nor of its desktop versions or of the git command line. While I've been maniacal about some additional features, on the other hand the plugin definitely lacks additional services offered by existing clients or command line, such as file-by-file control, request management, messaging and social, project management and more. The plugin was born from a personal need, that is to be able to upload as quickly as possible any of my changes to the repositories that I have on GitHub, but always maintaining a good control over the entire flow of data and files. So, in parallel to the first projects that I developed with Godot, I decided to develop a small custom system to perform the main operations I needed: navigate through all my repositories, make a push or pull, delete individual items or entire folders directly from remote, and write gists to note the updates of my projects. As the tool grew, it required less and less attention from a code perspective, since each of my commits consisted of a real stress test for any possible error (corrupted files, files too big, unreadable files). After less than a month of use and perfect functioning without any hiccup, sure that the feeling provided by the plugin was exactly the same, if not faster, than any external GitHub client, I decide to publish it through the Godot Engine AssetLibrary and release it under MIT license on GitHub, following the open source philosophy of the entire architecture on which it is based (Godot Engine itself).

Thus was born Github Integration, a tool born for personal needs, but exactly able to meet the main needs of an average user or a small team of developers.

Main Features

The combination of specific needs and care for the management of the interface and elements, led me to the development of some features that I consider very useful, not only personally but especially from the feedback received. Among these features that I consider custom, are certainly noteworthy:

  • Essential home page

    Godot_v3.2.4-rc3_win64_WGhj2En4DT.png
  • Integrated Editor for Gist

    Godot_v3.2.4-rc3_win64_0N9HJnK4UN.png
  • Resource Manager per Repository

    Godot_v3.2.4-rc3_win64_rPCqcZXE2l.png
  • Real Time Editor per .gitignore durante Commit&Push

  • Resource Manager per Commit&Push

    Godot_v3.2.4-rc3_win64_o1PCLA9vve.png
  • Fully costumizable settings

    Godot_v3.2.4-rc3_win64_MZtObtarMn.png
  • Collaboration management

    Godot_v3.2.4-rc3_win64_9RBMErJZ6h.png
  • Dark Theme!

    Godot_v3.2.4-rc3_win64_4ASv7V7pBI.png

Design and Functioning

Github Integration takes advantage of the REST API v3 and GraphQL API v4 made available by GitHub.

REST APIs are specific API entities whose architecture is based on the HTTP protocol. Specifically, REST APIs make available specific resources identified by a unique URL, on which calls can be made through specific clients (Postman) or programming languages equipped with HTTP Request APIs or libraries.

For example, a resource foo1 may be available at http://rest.apis/foo1, whereas foo2 may be reachable at http://rest.apis/foo2.

In my case, Godot Engine provides an entire class dedicated to HTTP requests, which I have specifically exploited to make all the calls necessary to perform basic operations with GitHub.

_Diagramma vuoto.png

The Commit and Push process is definitely the most time-consuming one, since its completion depends on the amount of files you want to add to the repository, and their size. Also, since GitHub has a maximum limit on the size of files that can be uploaded to a repository (it must not be larger than about 100MB), files of that size cannot be added by direct upload. Although the plugin already implements the ability to support git lfs without configuring it on your computer, I've blocked that functionality by default, as the git LFS API is currently not very responsive. To be loaded, each file must be replaced with a blob, which is a converted version with an encoding specified by the GitHub API. Below is a small example of the algorithm that takes the file, converts it, and adds it to the commit tree.

Godot_v3.2.1-stable_mono_win64_LDcV0TJnl8.png

The HTTP request will contain bodies in JSON format:

Godot_v3.2.1-stable_mono_win64_y4EIO7xY3o.png

All those operations that don't require uploading files (in the form of Bytes) are actually implemented by the counterpart of APIs provided by GitHub, which are the GraphQL ones.

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. Unlike REST APIs, resources provided by GraphQL are not routed through different urls and endpoints as identifiers, but instead take advantage of using just one unique url (https://api.github.com/graphql) which offers an interface to all resources made available by the server thorugh a Schema. So, to reach a resource, the only requirement is to know the schema, which is always made public by the provider of the GraphQL endpoint, and based on that structure users can get all the resources they want using queries and mutations.

From the engine perspective, issuing GraphQL queries with Godot Engine is as easy as issuing HTTPRequests to Rest Apis. The only big difference is that each single HTTPRequest will always point to the same endpoint and most of the time will be a POST request, but with GraphQL queries the payload will be way more complex and big.

Installation and Usage

I've created a Wiki directly using the tools provided by GitHub, containing all the necessary information on the installation of the plugin and its use. You can reach the wiki here.