Using GitHub

GitHub is a web-based hosting service for software development projects that use the Git revision control system.

GitHub offers both paid plans for private repositories, and free accounts for open source projects.

Laboratories and GitHub organizations

Developer Cloud Sandbox laboratories have a one-to-one relationship with GitHub organizations meaning that every laboratory has an equivalent GitHub organization.


According to your plan, the GitHub organization can host private repositories

Organizing the GitHub teams

Whithin a GitHub organization, you can organize as many teams including any number of members (typically developers).

Owners have full access to all repositories and have admin rights to the organization.

Created teams can have several levels of privileges:

  • Read Access: This team will be able to view and clone its repositories.
  • Write Access: This team will be able to read its repositories, as well as push to them.
  • Admin Access: This team will be able to push/pull to its repositories, as well as add other collaborators to them.


We recommend managing teams with a reduced number of member within a team with write access. The remaining team members with Read only access are invited to fork the repository and submit pull requests. The owners can then moderate these requests.

Organizing the repository

The repository should follow the structure below: # the markdown file used to generate the html summary seen at the bottom of projects.
.gitignore # Git uses it to determine which files and directories to ignore, before making a commit.
pom.xml # the Project Object Model file containing information about the project and configuration details used by Maven to build the project
/src # root folder of the application
    /java # if your application has Java code
    /resources # resources used to build the application
    /R # if you application has R code
    /python # if you application uses python code
    /doc # use this folder to document the application

You can use the following procedure in order to easily prepare the recommended structure for your Application:

  • Log on your Cloud Sandbox, and type:
mvn archetype:generate
  • Select the entry relative to the application archetype you want to use.

Currently, archetypes are available for: python, bash.

In this example, the option 2 (bash) is selected:

Choose archetype:
1: -> (Archetype for Developer Cloud Sandbox Python Applications)
2: -> (Archetype for Developer Cloud Sandbox Bash Applications)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 2
  • Then set the ‘groupId’, ‘artifactId’, ‘version’ and ‘package’ values for your project.

For example:

Define value for property 'groupId': : com.terradue
Define value for property 'artifactId': : myapp
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  com.terradue: : myapp

NOTE: the ‘version’ will be set by default to ‘1.0-SNAPSHOT’.

After that, you will see a folder with the name of the artifactId (here myapp).

See also

Have a look at the application tutorials which implements the recommended structure:

The typical application development workflow

Cloning an existing repository

You’ll need the SSH clone URL in the form:

Log on the sandbox using your key:

ssh -i ~/.ssh/<name>.pem <sandbox ip>


ssh -i ~/.ssh/mrossi.pem

Run the commands on the shell:

git clone


You will be interactively asked for your Github credentials for accessing private Github repositories.

Creating a new repository on

The procedure is describe here:


Make sure to create a file to enable cloning as described above

Building the application

Once the repository contains the structure described above, use maven to build and install the application for you:

cd ~/dcs-beam-flh-java
mvn install

This will use the information available in the pom.xml file to:

  • Compile the BEAM Java code and copy the JARs in the right spot
  • Copy the app-resources files to the /application file system.

At this point you can use ciop-run to test the application.


Do not edit files in /application, do it in the cloned directory and then run mvn install again. This will help you maintain the application repository aligned

Updating files

Whilst editing the files in /application may seem the most obvious way to change your application it also the way to loose changes.

In fact, you should edit the files in the source which has been cloned in your /home folder and use mvn install to update the build which is in /application with mvn install

Releasing the application

The pom.xml also contains information to create releases in GitHub.

To create releases of the application on GitHub use mvn deploy:

cd ~/dcs-beam-flh-java
mvn deploy


You can create pre-releases of the application by setting the version in the pom.xml with <version>x.y**-SNAPSHOT**</version>

Documenting the application

We suggest using the GitHub Pages.

The GitHub pages are public webpages freely hosted and easily published through the GitHub site.

GitHub pages can be managed manually or using frameworks. We suggest using R Gitbook or Sphinx as documentation generator tool that converts marked-up plaintext files into properly formatted HTML, PDF, EPub or other documents.


the GitHub pages of a private repository will be public and thus visible to anybody!

To create the GitHub Pages for the project, a new branch and do some one-time setup have to be performed.

The pom.xml file contains the information on how to build the documentation and update the gh-pages repository branch.

Documenting the application with Sphinx

Start the setup on Sphinx with the command:


Sphinx uses make to generate the documentation, so edit the Makefile provided to add a new variable called GH_PAGES_SOURCES which will contain files and directories that contain the documentation sources.

GH_PAGES_SOURCES = docs/source soccermetrics docs/Makefile

After a few minutes, open the browser at http://<organisation><repo name>

Documenting the application with R Gitbook

Going further

There are several high quality free ebooks on the Web (e.g., and GitHub provides a comprehensive web-site to get started here: