How to integrate GitHub into Woodford for smarter collaboration on your mobile projects
GitHub is a well-known collaboration platform focused on code sharing and version control. Thanks to the integration of GitHub into Woodford, you are able to log the history of changes made in your mobile projects. You can also use this feature to revert back to older versions of projects.
Furthermore, multiple users can now cooperate and store their progress in a single repository with no data loss. Thanks to GitHub integration, moving projects between organizations is much easier and safer, since multiple organizations can connect to the same backing repository.
Learn how to integrate GitHub with Woodford for deeper collaboration on mobile projects.
- Logging and auditing of the history of changes, version control
- Restoring previous committed versions
- Getting newer versions
- Importing projects that were created and customized by other users
- Multiple users working on the same project
- Moving the projects between organizations
- Moving projects between development, testing and production environments
When working with GitHub, there are 2 new terms that are important – repository and commit. Understanding those, you should have enough knowledge to use GitHub with Woodford. Additionally, GitHub also has a rich support page.
To start using the integration, you need a GitHub account with a repository. A new account and repository can be created following this tutorial. New repository has to be initialized in order to work within our environment.
Woodford writes into the ‘Projects’ folder in master branch of the GitHub repository. This needs to be taken into account especially when using preexisting repositories. In general, it is recommended to prepare a separate repository for each CRM organization and to use it only for Woodford projects.
The basic UI is located in the GitHub section of Woodford’s header in the Mobile Projects section. It consists of 3 buttons:
- Commit – for exporting a new version of the mobile project to GitHub (also located in the project detail page)
- Checkout – for importing a version of the mobile project from GitHub
- Configure – for setting up the connection to GitHub
Both Commit and Checkout button will stay inactive until the user configures a connection to a GitHub account. The Commit button also needs a mobile project to be selected to become active.
The usual workflow of using this new feature is that the user configures the connection, then commits the project after each set of changes. From time to time, the user can make a mistake or customers change their mind. Then they checkout one of the previous versions of the project from GitHub.
The other frequent use is that the user has to work on a previously prepared project, which is stored on GitHub, for example in a company account. The user configures the connection and checkouts the project. After some work, they can commit their changes back to the GitHub project or prepare a different GitHub project to commit.
This button serves for setting up the GitHub connection. After clicking on it, a pop-up window appears. Here the user needs to enter the GitHub credentials:
- Account Name
- Repository Name
- User name (e-mail)
- Select branch (Connect first using the ‘Connect’ button)
Account name can be either the name of a personal account or the name of an organization’s account. To decide which account name to fill in, simply open the page with your repository and check the full name of the repository. It is in a format: account_name/repository_name.
First, fill in the credentials – account name, repository name, user name and password. Then click on the “Connect” button. All available branches will appear after a successful connection. After choosing a branch, click on the “Save” button.
A new branch can be created in GitHub. Otherwise, it is possible to work only with the default branch “master”.
GitHub connection password is stored in Session storage, and thus it is persistent until the tab is closed. If a connection is configured, but the password was cleared (by closing the tab), all buttons stay enabled. User is prompted to fill in the password before performing Commit or Checkout operations.
After changing a mobile project, users can commit those changes to GitHub. To perform this operation, the Commit button is used.
It is strongly recommended to save the changes in Woodford before the commit. If there are unsaved changes, a warning will be prompted.
After clicking on Commit, a new window pops up (image on the left). Project Name and Branch Name are pre-filled and cannot be changed. User fills in the Description field and then clicks on the Commit button. Progress-bar shows the commit’s progress. When finished, a message with success or error information appears (image on the right).
In the GitHub repository, all commits can be found after clicking on the link highlighted in red below. The purple highlights show where the list of branches can be found:
After clicking on a particular commit in GitHub, users can see all differences between the selected and the previous version. If any files have been deleted in the commit, each deleted file will be shown as a separate commit. The commit message (description) is shown only next to the changed files. This is due to the versioning technology GitHub uses.
This button is used to retrieve a particular version of the project from GitHub repository. This can mean:
- restoring an older version of a project
- getting collaborator’s latest changes
- importing pre-existing project to an organization
- moving project from a development to production environment
- and more
After clicking on the Checkout button, a dialog window with GitHub projects appears (image on the left). If a project in the project list was previously selected, this project will be pre-selected (if it exists on GitHub). Or, the user can choose another project and click on the Select button.
Subsequently, all commits from the selected project are shown (image on the right). Commits can be sorted by date or by message. Clicking on the Checkout button at the bottom of the pop-up window checkouts the selected commit.
Loading a project from GitHub might take some time – a change to Resco’s API, enabled us to extend the limit for checkout of one file to 100MB (compared to 1MB previously). A dialog window with a progress bar is shown during the process (see below).
If there was a project selected in the project list before checkout, a dialog appears. It offers three options:
- Overwrite – overwrites the project which was selected in the project view with the selected version from GitHub
- Create new – creates a new project – Import Mobile Project dialog appears
- Cancel – cancels the checkout process
In case no project was selected, the Import Project dialog appears automatically (the user will create a new project).
First commit of the mobile project creates a folder with its name in the GitHub’s Projects folder. Each project has its own folder:
Each mobile project’s folder contains every file of that specific mobile project. The files located in this folder contain a list of entities, server configuration and mobile project’s settings.
The rest and most of the files are organized in 2 basic folders:
- Configuration (contains the configuration files (i.e. SyncFilter.xml) together with localizations)
- Controllers (contains all files representing forms, lists and charts together with style and themes)
This is how the default unedited Mobile project’s file structure looks like:
Additional folders will be created when necessary:
- Images (stores custom images)
- www (contains custom HTML files)
This is how the structure of the customized project can look like:
Resco strongly discourages all users to edit these files directly! In rare cases, files in folders “www” and “Images” can be edited, however editing other files outside of Woodford can lead to severe problems within the mobile project!
In case you have any questions, ask us at firstname.lastname@example.org. You can also check out even more new features from Resco’s Spring Update 2019 here.