How to use Repository

If you have a repository you want to use within Easy Project, here is how to connect it.

 

Table of contents

What is an SCM repository
How to set up global repository settings
How to activate repository on a project
Configure automatic repository updating

 

What is an SCM repository

In computer software engineering, software configuration management (SCM) is any kind of practice that tracks and provides control over changes to source code. Software developers sometimes use revision control software to maintain documentation and configuration files as well as source code. Revision control may also track changes to configuration files.

As teams design, develop and deploy software, it is common for multiple versions of the same software to be deployed in different sites and for the software's developers to be working simultaneously on updates. Bugs or features of the software are often only present in certain versions (because of the fixing of some problems and the introduction of others as the program develops). Therefore, for the purposes of locating and fixing bugs, it is vitally important to be able to retrieve and run different versions of the software to determine in which version(s) the problem occurs. It may also be necessary to develop two versions of the software concurrently (for instance, where one version has bugs fixed, but no new features (branch), while the other version is where new features are worked on (trunk).

At the simplest level, developers could simply retain multiple copies of the different versions of the program, and label them appropriately. This simple approach has been used in many large software projects. While this method can work, it is inefficient as many near-identical copies of the program have to be maintained. This requires a lot of self-discipline on the part of developers and often leads to mistakes. Since the code base is the same, it also requires granting read-write-execute permission to a set of developers, and this adds the pressure of someone managing permissions so that the code base is not compromised, which adds more complexity. Consequently, systems to automate some or all of the revision control process have been developed. This ensures that the majority of management of version control steps is hidden behind the scenes.

Moreover, in software development, legal and business practice and other environments, it has become increasingly common for a single document or snippet of code to be edited by a team, the members of which may be geographically dispersed and may pursue different and even contrary interests. Sophisticated revision control that tracks and accounts for ownership of changes to documents and code may be extremely helpful or even indispensable in such situations.

 

How to set up global repository settings

To access global Repository settings, go to More > Administration > Settings > Repository. The setting options are as follows:

• Enabled SCM - Select which SCM you want to enable. The list shows all supported repository clients and their statuses (green icon = installed; red icon = not installed). On the right side is information about versions of the installed ones. Always check if a repository client is installed on the server before you try to set it up.
• Fetch commits automatically - If this option is activated, the application automatically retrieves the new revisions when a user consults the repository.
• Enable WS for repository management - This option must be activated if you want repositories to pull revisions automatically from the original repository. You also need to have enabled the respective webservice on the original repository - see chapter below.
• Referencing keywords - Define referencing keywords for tasks in commit messages. Use reference keywords to link revisions to tasks in Easy Project.
• Fixing keywords - Define fixing keywords for tasks in commit messages. Fixing keywords allow task status or progress changes using certain keywords in commit messages.
• Assignee - Define which assignee will be applied to a task if a fixing word is used in a commit message.
• Applied tasks - Define task status if a fixing word is used in a commit message.
• % Done - Define which percentage of done is applied to a task if a fixing word is used in a commit message.
• Allow tasks of all the other projects to be referenced and fixed inline - Allows using GIT to directly reference or close tasks only by writing in a correct keyword and ID of the task into a commit message. It works cross-project.
• Enable time logging - Activating this option enables logging time to a task via commit message.
• Activity for logged time - Define activity for logged time. This activity is used for time logging via a commit.

Don’t forget to save your changes by clicking on the green "Save" button.

Note: You can configure your SCM commands in config/configuration.yml. Please restart the application after editing it.

 

How to activate repository on a project

Before you can start using the repository, you must enable the respective module on a particular project. To do so, go to the project's Settings > Modules > tick the checkbox Repository > Save your settings. Immediately after saving, the Repository tab appears in the project's top menu.

Click on the Repository tab and the following form opens. Here you can adjust the global default settings on how to fetch commit messages for this particular project. When left unchanged, the global settings apply. To create a new repository, click on the respective button on the upper side.

When creating a repository, the setting options are variable depending on which type of SCM repository you select. On the following screen, select a type of SCM repository (such as Subversion, Darcs, Mercurial, CVS, Bazaar, Git), check if it's the main repository, your own identifier, URL to the repository, path to the repository (if required), path encoding (if required), login name and password to the repository (if required) and other details. Check with your SCM repository provider on how to fill in the respective fields if you don't know. When finished, click on the "Create" button below to create the repository.

IMPORTANT: Most Git servers require authorization with either a key or http basic auth. If you prefer key authorization, we will provide you with a public key on request that you can simply add to your GitLab/GitHub. So instead of http(s)://user:password@url/repo.git, it will be in form of http(s)://user:repoclienttoken@url/repo.git

This is how looks a form to create Git repository.

This is how looks a form to create Subversion repository.

When one or more repositories are created, you can find a list of them on the project repository page as illustrated below.

On the right side from the list, you can find a few options:

• Users - Select or update the Easy Project user mapped to each username found in the repository log. Users with the same Easy Project and repository username or email are automatically mapped.
• Edit - Edit the repository settings
• Delete - Delete the repository

Below you can see an example of Users setting.

If everything is set up correctly, you should be able to see the files from the repository in Easy Project as on the below example.

 

Configure automatic repository updating

Repository client and Easy Project are two different applications. New commits into your repository are not reflected in Easy Project unless they are fetched by the application. You need to set webhooks on your repository client (GitHub, GitLab, TortoiseSVN,...) with information about your Easy Project instance.

1. Go to administration >> settings >> repositories
2. Enable WS for repository management
3. Generate an API key
   
   
    
4. Save
5. Go to your repository client
6. Add a webhook
   Let's say your site is easyproject.company.com
   For GIT - https://easyproject.company.com/sys/git_fetcher
   or https://easyproject.company.com/sys/git_fetcher?key=[API_key]&fetch_all=1 => to fetch all repositories on all projects
   or https://easyproject.company.com/sys/git_fetcher?key=[API_key]&project_id=1234&fetch_all=1 => to fetch all repositories on project ID=1234
   - the "project_id=" parameter must contain a project ID (automatic number in the database), not a project identifier (custom text), which are two different data
   - depending on client setting, it may require a single URL or the key into a different field
   For SVN - https://easyproject.company.com/sys/fetch_changesets
   or https://easyproject.company.com/sys/fetch_changesets?key=[API_key]

From point 5, it is all up to the repository client and not related to Easy Project settings. It is something you must verify after clean installation or upgrade from Easy Project.