Securing Design Source inside a Design Repository

Created: July 31, 2017 | Updated: July 31, 2017 | Applies to version: 17.1

Now reading version 18.0. For the latest, read: Securing Design Source inside a Design Repository for version 17.1

Parent page: Managed Board Design Release

The best way of working from a known set of source files is to store the design project in a controlled environment, such as a version control repository. This is important because the only way of ensuring the outputs come from the correct source files is to:

Confirm that the source fileset is up-to-date.
Take a snapshot of them.
Generate outputs from that snapshot.

In Altium Designer, such a repository is referred to as a Design Repository. Owned by the design team, the Design Repository contains a high-resolution view of the history of the design process and is the primary collaboration tool used by the design team.

The Design Repository becomes the central repository from which multiple team members can check data in and out, all the while maintaining a complete revision history of all changes made to the design. A design is therefore stored as a series of versions of its constituent project and source documents, building a progressive picture of the intent of a designer over time. By using a version-controlled Design Repository, you have the integral assurance that no revision of a design is ever lost, allowing for safe collaboration on the same design between members of a team that can be geographically dispersed in their locations. The very nature of the version control system provides an audit trail for the design. Full accountability arises through transparency of whom changed what, in which source document, and when. The system can support multiple version-controlled Design Repositories with the link to a particular repository being established by the version control link within the project folder.

By connecting to a Design Repository you are, in effect, registering that repository with the system - telling Altium Designer of its existence as it were. Furthermore, there is no manual specification of paths to unofficial or 'rogue' repositories. Through Altium Designer, you can only interact with those VCS-based Design Repositories you have purposefully connected to the system.

Supported Version Control

The version control software - used to implement the repositories themselves - is supported in the following ways:

Through Altium Designer - both Subversion (SVN) and Concurrent Versions System (CVS) version control providers are supported for implementation of Design Repositories. Altium Designer includes Subversion capabilities built-in. Version control providers are enabled and configured on the Data Management - Version Control page of the Preferences dialog (DXP » Preferences).

SVN - Subversion is enabled by default, with built-in Subversion capabilities delivered through the VCS Provider - SVN extension. This extension is installed by default, and delivers a better implementation of version control functionality, through the use of SharpSVN. This implementation has full support for Unicode (multi-byte) characters in file names. This for example, allows you to add files to your SVN VCS repository that include Russian characters in their names.

If you require to use the older Subversion VCS functionality, based on use of the SVN executable (svn.exe), you can effectively roll back to this implementation by removing the VCS Provider - SVN extension from your installation. You can use the Subversion that is built-in to Altium Designer, or you can use your own external Subversion installation. If the latter, you must also ensure that the paths to the SVN executables have been specified.

Roll over the image to show the difference in the Data Management - Version Control page when the VCS Provider - SVN extension is
installed (default), and removed (giving the previous system).

Through an Altium Vault - an appropriately licensed Altium Vault installation provides localized (and centralized) version control, courtesy of its Version Control Service. Essentially an SVN server, this service provides version control possibilities right there where you need them, locally, without searching or paying for external SVN management software.

Managing Design Repositories

Design Repositories are managed on the Data Management - Design Repositories page of the Preferences dialog. From this page you can perform a number of actions, including:

Creating new file-based repositories using version control available through Altium Designer (built-in, or external installation).
Connecting to existing repositories.
Browsing repositories shared for use through the Altium Vault's local Version Control service.
Controlling the active state of each defined repository.

The Data Management - Design Repositories page - command-central for managing VCS-based Design Repositories within Altium Designer.

For each registered, or rather connected repository, the following information is presented:

Name - a meaningful name for the repository. This could, for example, reflect the design projects that are stored in the repository. This name is used elsewhere in the software for quick selection of a Design Repository to be used, for example when opening a project from version control.
Activated - whether the repository is available for use by the system (enabled) or not (disabled). A newly created or connected repository will be activated by default.
Type - the type of repository. For a repository defined through Altium Designer, this can be either SVN or CVS. For a repository defined through the Altium Vault's local Version Control service, this is SVN.
Repository - the URL to the root folder of the repository.
Status - whether the connection between Altium Designer and the repository is successful () or not (). If connection is unsuccessful a comment will be displayed, indicating the problem.

Creating a New Repository through Altium Designer

Creation of new Design Repositories from within Altium Designer is performed from the Data Management - Design Repositories page of the Preferences dialog. Simply click the Create New button and choose the type of repository you wish to create - either SVN or CVS - from the associated drop-down menu. The applicable creation dialog will appear. For an SVN repository, this is the Create SVN Design Repository dialog. Use this to give the vault a meaningful name, specify a default checkout path, and specify the location for the repository. If a folder is specified that does not currently exist, it will be created for you.

By default, the repository will be named Repository 1. Change this to a more meaningful name as required. There are no restrictions on naming when creating a repository that is external to an Altium Vault.

The Repository Location can either be on your hard drive (for your own personal use) or in a network location (for collaborative use by a wider team).

With all settings specified as required, click OK. The repository will be created at the nominated location and a connection to that repository from Altium Designer made. An entry will appear for it in the listing of Design Repositories back on the Data Management - Design Repositories page of the Preferences dialog.

Example newly created SVN Design Repository, appearing within Altium Designer as Local Repository.

Currently, only Design Repositories with the file repository access method can be created directly from within Altium Designer. A Design Repository using a different access method (e.g. networked access over http or https) can be set up outside of Altium Designer using an external SVN interface tool, provided that tool bundles with it the Apache web server required to facilitate the http access method. Alternatively, get the repository setup by your network administrator, or use one of the many providers of hosted Subversion repositories. You can then connect to that existing repository from within Altium Designer.

Creating a Repository through the Altium Vault

Repositories can be created through the Altium Vault's local SVN server, or external repositories can be connected to. Together, all repositories are centrally managed through the VCS page of the vault's browser-based interface.

The VCS page can only be accessed by an administrator for the vault (a member of the Administrators role). Click on the ADMIN entry at the top of the interface, then choose the VCS entry from the menu.

To add a Design Repository, simply click the Add Repository 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 VCS 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.

For a fresh Altium Vault installation, a default Design Repository is available, named DefaultRepository. Manage user access to this repository as 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.

Create a new SVN-based Design Repository, or link to an existing one.

Design Repositories defined through the Altium Vault are populated to the client automatically during sign-in, so users do not have to worry about urls, protocols, passwords etc. A repository is simply configured once, on the server, and shared with the intended users as required.

You may need to sign out and sign in again for the repository to appear on 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 VCS 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.

Connecting to an Existing Repository through Altium Designer

In a collaborative environment, one or more Design Repositories may already have been created in a location accessible by multiple users. In this case, you do not need to create a new repository - re-inventing the wheel as it were - rather you simply need to connect to the required existing repository. This is also the case if you have removed a repository from your list of repositories, and want to add it back in again.

To connect to an existing repository, simply click on the Connect To button and choose the type of repository you wish to connect to - either SVN or CVS. The applicable connection dialog will appear. For an SVN repository, this is the SVN Design Repository dialog. Simply enter a name by which to refer to the repository from within Altium Designer, specify a default checkout path, and specify the repository access method and path to the root folder of the repository. You can also specify a particular sub-folder within the repository.

With all settings specified as required, click OK - a connection will be made and the repository will be ready for use.

Connecting to an existing repository - in this case a repository internal to an Altium Vault installation.

Editing Repository Properties

You can also edit the properties of a Design Repository at any time. For example, you might want to change the name of the repository, as displayed and referenced within Altium Designer. Or you might want to edit the connection, perhaps to link to a different repository. To do this, simply select the entry for the repository in the listing of repositories, then click on the Properties button. The applicable Design Repository dialog will appear, from where you can make changes as required.

For a Design Repository added through the Altium Vault's browser-based interface, only the Name and Default Checkout Path can be modified. Any other required changes must be performed from the VCS page of the browser interface.

Disconnecting from a Repository

To disconnect from a Design Repository, simply select its entry in the list and click the Remove button. The repository is removed from the list of connected Design Repositories. The repository itself - the SVN or CVS repository - is not deleted, it simply becomes disconnected from the system. To use a repository again, simply connect to it.

To disable use of a Design Repository, without removing it completely from the list, simply disable its associated Activated option.

If you remove a Design Repository that has been added through the Altium Vault's browser-based interface, you can connect to it again. Alternatively, and far quicker, close out of the Preferences dialog, then sign out from the Altium Vault and sign back in again. When you access the Data Management - Design Repositories page of the Preferences dialog again, those repositories added through the vault interface will be present once again.

Using Design Repositories

Once defined, the connected nature of a VCS-based Design Repository simplifies the ability to either add a project to that repository, or open an existing project from that repository. Instead of having to remember the path or drill down in a browse menu to select the repository, you simply choose the required repository from a convenient listing of all Design Repositories you are currently connected to, and that are activated for use.

Adding a Regular Project to a Repository

Adding a Regular design project to a Design Repository is a straightforward process. With the project open, use the Add Project Folder To Version Control command from either the Projects panel or Storage Manager panel. The Add to Version Control dialog will appear. The field at the top of this dialog presents a drop-down listing of all connected and activated Design Repositories. Select the repository required.

Click the

button to quickly access the Data Management - Design Repositories page of the Preferences dialog - if you need to connect a different repository, or create a new one.

The folder hierarchy within the chosen Design Repository is presented to you in the Folders region of the dialog. Either specify an existing folder into which to add the design files, or create a new folder using the New Folder button. In the latter case, a folder will be added at the specified position within the repository's folder hierarchy, named after the source folder containing the project.

Connected VCS-based Design Repositories make adding Regular design projects to version control a snap!

Creating a New VCS Project

When creating a new VCS project, the Repository field in the New Project dialog presents a drop-down listing of all connected and activated Design Repositories. Select the repository required.

Creating a new VCS design project - all defined Design Repositories are available for use.

Adding a Managed Project to a Design Repository

Related page: The Managed Project

Whether creating a new managed project, or converting an existing design project (Regular or VCS) to a managed project, the resulting project is stored in a Design Repository. As part of the respective interface used to create/convert, the repository can quickly be selected from a list of defined repositories.

Only those managed Design Repositories added through the Altium Vault's local SVN service, and which have been shared with you to use, will be listed. Other Design Repositories that have been created directly through the Data Management - Design Repositories page of the Preferences dialog, will not be available for use as target repositories.

Creating a new Managed design project. Only Managed Design Repositories (added through the Altium Vault's local SVN service) that are
shared with you, will be available for use.

A Regular design project being converted to a Managed project. The target Design Repository must be of the managed variety - added through the Altium Vault's local SVN service.

The newly-created/converted managed project will subsequently be available from the Projects page of the vault's browser interface.

Opening a VCS Project from a Design Repository

Equally straightforward is the ability to open a VCS design project that resides in a Design Repository. Simply use the File » Checkout command - the Check Out dialog will appear. Use the Check out from field to choose the required repository from a drop-down listing of all connected and activated Design Repositories.

Click the

button to quickly access the Data Management - Design Repositories page of the Preferences dialog - if you need to connect a different repository.

The folder hierarchy within the chosen Design Repository is presented to you in the Folders region of the dialog. Use this region to specify the exact folder that is to be checked out from the repository.

Use the Check out to field to specify where the nominated folder content is to be checked out to. This is your local sandbox area for example.

Check out an existing version-controlled design project from a nominated Design Repository with controlled ease!

Opening a Managed Project from a Design Repository

To work on a managed project - essentially checking out as a local working copy - use the File » Open Managed Project command. The Open Managed Project dialog will appear, from where you can choose which managed project to open. Only those Managed Projects that have been shared with you (you have permission to access) will be listed, and from across all managed Design Repositories shared with you.

Choose which managed project to open, from those currently shared with you.

Printer-friendly version

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.