Parent page: Altium Vault
The Altium Vault installation provides localized (and centralized) version control, courtesy of its Version Control service. Essentially an SVN server (version 1.8), this service provides version control possibilities right there where you need them, locally, without searching, or paying for, external SVN management software.
By defining design repositories in this centralized fashion, an oganization can fully control which repositories its designers can access and use.
Key Advantages
There are two key advantages to using this centralized Version Control service:
- You have common users and rights management for both the Altium Vault and SVN. When you sign in to the Altium Vault, the Version Control service works with your session/credentials.
- Repositories defined through the Altium Vault (through the VCS page (ADMIN » VCS) of the Vault's browser-based interface) are populated to the client automatically during login, so users do not have to worry about urls, protocols, password etc. It is simply configured once, on the server, and shared with the intended users as required.
When a new user for the Altium Vault is created, the defined Password for that user is stored in both the Vault and the SVN service, since the latter cannot access the password from the former directly. If you have upgraded a previous installation of the Altium Vault (1.1, 1.2), existing users will not have a password stored with the SVN service. Access to Version Control (and Managed Projects) will not be possible until this is resolved. To do this, simply re-create each user's password.
Repository Creation
Repositories can be created through the local Version Control service, or external repositories can be connected to. Together, all repositories are centrally managed through the VCS page (ADMIN » VCS) of the Vault's browser-based interface, in terms of:
- Their displayed name, description and repository path.
- Their configured accessibility - which specific users can access them (or roles in the case of repositories defined through the local Version Control service).
- Their availability - add or remove them centrally, rather than individual designers having to create and connect to repositories independently.
A default Design Repository is available, provided by the local Version Control service and named DefaultRepository. While you cannot rename this repository, you can add a description for it, manage user access to it, or remove it, as required.
When a user signs in to the Altium Vault, the Design Repositories available to them will automatically be added to the Data Management - Design Repositories page of the Preferences dialog.
Centrally define access to your organization's Design Repositories. Repositories can be internal to the Altium Vault installation, defined using the local Version Control service, or external
through use of Altium Designer's built-in SVN, or third party SVN service. Access control is performed through the VCS page of the Altium Vault's browser-based interface. When a user
signs in to the Altium Vault, the Design Repositories available to them will automatically be added to the Data Management - Design Repositories page of the Preferences dialog.
Adding a Repository
To add a Design Repository, simply click the 
button, located at the top-right of the page. The Add Repository window will appear, use this to define the repository. The properties required depend on whether you are creating a new repository using the local Version Control service, or linking to an existing, external repository:
- New - simply give the repository a name and a description.
- Existing - in addition to a name and description, you need to supply the URL to the repository, and your credentials (User Name, Password) to access that repository (if required).
When creating a repository that is internal to the Vault, the name should start with, and can contain A-Z, a-z, or 0-9. Underscores, dashes, and spaces are allowed within the middle of the name. You can not use the following words: AUX, COM1-COM9, LPT1-LPT9, CON, NUL, and PRN. There are no naming restrictions for an external repository.
Create a new SVN-based Design Repository through the Vault's local Version Control service, or link to an existing one that has been created external to the Vault.
A linked, external Design Repository is distinguished in the list of repositories by its External property being ticked (
).
To edit the properties of a Design Repository at a later stage, simply click its associated Edit control (
). To remove a Design Repository, simply click its associated Remove control (
).
The list of repositories is automatically sorted alphabetically by Name, with local repositories defined through the Version Control service listed first, and then external repositories thereafter.
Sharing a Repository
Having centralized your Design Repositories, you need to ensure that those requiring access to a given repository - including the designers who will be working on board designs - have that access. This is achieved by sharing that repository, or rather managing its access permissions. To do this, simply click on the repository's associated Share control (
).
The Manage Permissions window will appear, with all the controls necessary to share the repository with other users.
With Design Repositories centrally organized, sharing with others is simply a case of managing each repository's permissions.
Things to be aware of:
- For a local repository created through the Vault's Version Control service (i.e. not external), that repository is shared, by default, with the user who created the repository, and the Administrators role. Both of these have full Read/Write access.
- For an external repository, it is shared with no-one by default - not even the user who added a connection to it through the interface.
- Only local repositories (not external) can be shared with defined roles for the Vault, or publically. Roles are listed after individual users.
- In terms of permissions, a user/role has Read/Write access when the Can Write option is enabled. If this option is disabled, they have Read access only.
- To remove an existing user/role from having shared access to a repository, click the associated Remove control (
).
Sharing a Local Repository with a Vault User
To share a local (not external) repository with another Vault user:
- Click the Add User control in the Manage Permissions window.
- In the Add Users window that appears, start typing the full name, username, or email address of a Vault user in the Select Users to be added field, to pop-up a list of matching users. Select the required user from this list. Multiple users can be chosen. To remove a user, simply click the delete cross, to the far right of their name.
- Set the permission for the user(s) using the Permission field. Use the drop-down to choose betwen Read access, or Read/Write access.
- Click the
button once ready, to effect addition of the user(s) and return to the Manage Permissions window.
- Click the
button in the Manage Permissions window.
To edit the permissions for an existing user, simply use the Can Write option in the Manage Permissions window, to toggle between Read/Write access (enabled) or Read-only access (disabled).
Sharing a Local Repository with a Defined Role
If the repository has been created through the local Version Control service, rather than an external repository, then you also have the ability to share with roles defined for your Altium Vault. To share a local (not external) repository with another role:
- Click the Add Role control in the Manage Permissions window.
- In the Add Groups window that appears, start typing the name of a role in the Select Roles to be added field, to pop-up a list of matching roles. Select the required role from this list. Multiple roles can be chosen. To remove a role, simply click the delete cross, to the far right of its name.
- Set the permission for the role(s) using the Permission field. Use the drop-down to choose betwen Read access, or Read/Write access.
- Click the button once ready, to effect addition of the role(s) and return to the Manage Permissions window.
- Click the button in the Manage Permissions window.
To edit the permissions for an existing role, simply use the Can Write option in the Manage Permissions window, to toggle between Read/Write access (enabled) or Read-only access (disabled).
Sharing a Local Repository Publically
If the repository has been created through the local Version Control service, rather than an external repository, then you also have the ability to share that repository publically - allowing all Vault users to access and use it. To share a local (not external) repository publically:
- Click the Add Public control in the Manage Permissions window.
- The Public entry will be added directly to the list of shared entities, and automatically shared for Read/Write access.
- Click the button in the Manage Permissions window.
To edit the permissions for the Public entity, simply use the Can Write option in the Manage Permissions window, to toggle between Read/Write access (enabled) or Read-only access (disabled).
Sharing an External Repository with a Vault User
To share an external repository with a Vault user:
- Click the Add User control in the Manage Permissions window.
- In the Add User window that appears, start typing the full name, username, or email address of a Vault user in the Select User to be added field, to pop-up a list of matching users. Select the required user from this list. To remove the user, simply click the delete cross, to the far right of their name. Notice that the SVN User field will populate with the same user name. While you can only add a single user at a time, you can define as many users for access to the external SVN repository as you need.
- Click the button once ready, to effect addition of the user and return to the Manage Permissions window.
- Typically, you might have the same user name (company domain user name) used for authentication when connecting to your Altium Vault, and your company external SVN repository. This is why the SVN User field is filled with the same user name selected for the Vault user. However, if this is not the case, you have the ability to change the SVN User name to suit your particular SVN access - mapping the Vault user to the SVN user, as it were. To do so, simply click the Edit control () to the right of the SVN User entry - in the Manage Permissions window - and enter the required user name in the SVN User field, in the Edit User dialog. Don't forget to click the button to effect the change.
- Click the button in the Manage Permissions window.
Access itself (Read-only, or Read/Write) is determined externally as part of the SVN repository installation. The Altium Vault has no access to the external SVN repository's authz file, and so cannot manage these permissions from the Vault side.
External Access to a Local SVN Design Repository
A Design Repository that is created through the local Version Control Service can be accessed using an SVN client such as TortoiseSVN. Access is made using the regular network protocol (only svn:// is currently supported). The correct repository address can be copied from two places:
- The VCS page of the Vault's browser interface - within the Repository Path field for the target repository.
The address will depend on whether you are accessing the repository from the same machine on which the Vault is installed (e.g. svn://127.0.0.1/<RepositoryName>, or svn://localhost/<RepositoryName>), or from a remote PC (e.g. svn://<ComputerName>/<RepositoryName>, where ComputerName is the name of the PC on which the Vault resides.
Use the acquired address in your Subversion client's repository browsing facility. To access the repository, you will need to sign-in using your Vault login credentials (when a user is created in the Vault, the credentials are used by both the Vault itself, and the Version Control service - see Version Control Service Passwords for more information).
Browsing the content of a Design Repository created through the Altium Vault installation's local SVN-based Version Control service. In the example above, the repository contains
a number of Managed Projects, providing the ideal foundation for centralized project management, and controlled collaboration between team members.
A Design Repository that is created through the local Version Control service has its internal data stored in a corresponding sub-folder in the \ProgramData\Altium\VaultServerData\Repository folder (for a default installation of the Altium Vault). This folder should not be accessed in any way, other than by IT personnel for maintenance. Access from this folder using your Subversion client's repository browsing facility does not require authentication.
Vault & VCS User Synchronization
When a new user for the Altium Vault is created, the defined credentials (User Name and Password) for that user are stored in both the Vault's database and the Version Control service, since the latter cannot access the password from the former directly. The password is stored with the Version Control service in plain text format (in the \VaultServerData\Repository\passwd file). If this presents a security issue, you can simply remove these password entries manually.
In a default installation of the Vault, user credentials are stored for the Version
Control service in the associated Passwd file. The passwords can be cleared manually.
User synchronization between the Vault and the Version Control service can also be disabled completely, alolowing you to specify usernames that feature Unicode symbols. This is made possible through use of an option in the LocalVault.ini file - VcsSync. For a default installation of the Altium Vault, the LocalVault.ini file can be found in the \Program Files (x86)\Altium\Altium Vault folder of the installation.
By default, this option is enabled (set to '1'), which means user synchronization is enabled. By setting this option to '0', user synchronization is disabled. The result of disabling the option is that when a new user is added to the Vault, the passwd file will not be updated to add that new user to the list.
IIS (Vault-related application pools) must be restarted after the change has been made and the INI file saved, in order for the change to be applied.
With user synchronization between the Vault and Version Control service disabled (VcsSync=0), a newly added user to the vault
will not be added to the local Version Control service's passwd file.
The option allows synchronization to be stopped. It does not clear the password entries for synchronized users created previously. You can, however, simply remove these password entries manually.
Note that while VcsSync=0, all actions relating to managed projects within local design repositories (created internal to the Version Control service) will be disabled. A new managed project can still be created, but only external repositories will be available for use as normal.
Deleting a Repository
To delete a repository from the Vault's Version Control service, simply click the Remove control () associated with that repository, on the VCS page of the Vault's browser-based interface.
Note that removing a repository from the
Data Management - Design Repositories page of the
Preferences dialog only removes that repository from being used by that instance of Altium Designer. It does not delete the repository from the Vault's Version Control service. If you sign out of the Vault and back in again, the repository will appear once more in the list of available repositories to that instance of Altium Designer.
External repositories can be deleted, irrespective of whether or not they contain any projects. Local repositories on the other hand (those created internally through the Vault's Version Control service) can not be deleted if they contain one or more projects. You will be alerted to this, and should remove the projects first before being able to proceed with deletion.
Even then, if a local repository has no projects, it will not actually be deleted, but rather moved to an archive directory (\ProgramData\Altium\VaultServerData\RepositoryDumps, for a default vault installation). The repository will be contained within a Dump file, with a Unique ID prefix (e.g. 775f6c22-b9a1-468c-9f1f-4f217bb3be6b_central design repository.dump).
