Parent page: Creating a Project
There are essentially two ways to work with projects:
- The recommended and most powerful method is to create a new project directly within the connected Workspace. If you have an existing project, you can bring it into your Workspace by making it available online and opting to enable formal version control. In each case, the project will be stored and managed through the Workspace’s native Version Control System (VCS). This gives you the full functionality for a project when working with it through Altium Designer. Having your project under full management of the Workspace's VCS is the only way to share that project with multiple people for editing through Altium Designer (provided they are members of the Workspace) and benefit from the platform's additional features such as History tracking and advanced project Sharing.
- A local project that is not under version control or is under external version control can be registered with your Workspace using a methodology called Simple Sync. A mirror of your project is created in the Workspace and synchronized. Once local file changes are saved (or saved and committed to the external design repository), those changes are automatically synchronized with their mirrored project counterparts in the Workspace. Simple Sync allows you to enjoy the collaborative features available through the Altium 365 platform while keeping your original project right where it is. However, bear in mind that for a local design project (not under external VCS), that project can be edited by a single person only (the owner of that project – the one who made it available online to the Workspace).
To make an existing project (a local project, or a local project currently under external version control) available to the Workspace – either as a project mirrored (Simple Sync) in an Altium 365 Workspace or one under a Workspace's native Git Version Control, open the project as normal in Altium Designer, then right-click on its entry in the Projects panel and select Make Project Available Online from the context menu, giving access to the Make Available Online dialog. When using an Enterprise Server Workspace, the Make Project Available on Server command opens the Make Available On Server dialog.
Make an existing local project available to the Workspace, essentially 'registering' it with the Workspace and creating a 'mirror' of it.
- Project Name – the name of the project in the Workspace. By default, the name will be that of the original project.
- Description – enter the desired description of the project.
- Version Control – check this option to add a local project to the Workspace's own built-in VCS (Git). If this option is unchecked, the project files will simply be stored in the Workspace for basic access and to enable sharing with others for viewing and commenting only – a less formal Simple Sync as it were. It is recommended to enable formal version control, as by doing so you will have access to the maximum functionality offered through, and by, the Workspace and the Altium 365 platform. This option is available only if the project is currently not under version control.
- Migrate to Altium 365 Versioned Storage – enable this option to migrate a project that uses an external VCS to a project under full management of the Workspace's VCS. Such a project can then benefit from the Workspace's native VCS features. This option is available only if the project is currently under an external VCS.
- Advanced – click to access an additional option.
- Folder – this field is used to specify where the folder for the project being migrated – within the Workspace's folder structure – is to be created. The default path for new projects is specified on the Admin – Settings – Projects page of the Workspace's browser interface (by default, this will be
Projects\<ProjectName>). Click to open the Choose Folder dialog, which is a trimmed-down version of the Explorer panel, from where you can browse and select a different server folder if required.
- Project Name – the name of the project in the Workspace. By default, the name will be that of the original project.
- Description – enter the desired description of the project.
- Migrate to Altium Versioned Storage – enable this option to migrate a project that uses an external VCS to a project under full management of the Workspace's VCS. Such a project can then benefit from the Workspace's native VCS features. This option is available only if the project is currently under an external VCS.
- Advanced – click to access additional options.
Use the Make Available Online dialog to change the project Name and add a Description. By default, the name will be that of the original project.
Check the Version Control option to add the project under the Workspace's own built-in VCS (Git). When this option is unchecked (an Altium 365 Workspace option only), the project files will simply be stored in the Workspace for basic access and to enable sharing with others for viewing and commenting only – the Simple Sync arrangement. It is recommended to enable version control, as by doing so you will have access to the maximum functionality offered through, and by, the Workspace and the Altium 365 platform.
If the local project is already under version control (an external design repository), the Migrate to Altium 365 Versioned Storage
option will be available in the Make Available Online
dialog. Learn more about Moving from External VCS to Workspace Native VCS
Project Sharing in an Altium 365 Workspace:
If the Version Control option is disabled – thereby using the informal Simple Sync feature for a local project (that is not under external VCS) – the design project can be edited by a single person only (the owner of that project, who is the one that made it available online to the Workspace). The strength of Simple Sync comes when you do not want anyone else editing your design, but where you do want to take advantage of Altium 365's Global Sharing paradigm and be able to share that design with multiple other people for viewing and commenting.
When the Version Control option is enabled – through the use of the Workspace's Versioned Storage Git-based design repository – then multiple people can be shared the project for editing, or for viewing and commenting.
Click the dialog's Advanced link to expose the Folder field. This field is used to specify where the folder for the mirrored project – within the Workspace's folder structure – is to be created. The default path for new projects is specified on the Admin – Settings – Projects page of the Workspace's browser interface (by default, this will be
Projects\<ProjectName>). Click the button to browse and select a different server folder, if required.
Note that ability to mirror a project in a Workspace (Simple Sync) is available only when connected to an Altium 365 Workspace.
With the properties for the project transition defined as required in the Make Available Online dialog, click OK. Projects that have been made available online – in the Workspace – will be shown in the Altium Designer Projects panel as follows:
(Altium 365 Workspace only) For a project that is not under external version control and made available online with the Version Control unchecked, the project is shown with the icon only. This indicates the project as being registered with the Workspace, that a mirrored project exists, and that the two are synchronized using the Simple Sync methodology. Saved local files are automatically synchronized with their mirrored project counterparts in the Workspace.
(Altium 365 Workspace only) For a project that is under external version control, the project is shown with the icon to indicate the project as being registered with the Workspace, that a mirrored project exists, and that the two are synchronized using the Simple Sync methodology. Associated icons reflect the fully synchronized state that exists between the external design repository and the local working copy. Once local file changes are saved and committed/pushed to the external design repository, those changes are automatically synchronized with their mirrored project counterparts in the Workspace.
For a project that is not under external version control and when made available online (in an Altium 365 Workspace, the Version Control option was checked), the project and files will be committed and pushed to the Workspace's Versioned Storage design repository. The Projects panel will then reflect the fully synchronized state that exists between the Workspace design repository and the local (working copy) repository, as indicated by the associated icons. The project becomes a true managed project – not just 'registered' in the Workspace, but actually committed and under the Workspace's version control. Any changes made to the design must be saved (committed/pushed) back to the repository in the Workspace.
The mirrored project will subsequently be available from the Projects page of the Workspace's browser interface.
The mirrored project will initially be shared for Read/Write access with the designer who created it (Owner), and all Administrators for the Workspace. For more information on configuring project access permissions, see Sharing a Project
Simple Sync States
Where a local project is made available online to an Altium 365 Workspace using the Simple Sync approach (not using the Workspace's version control), the current state of the synchronization between local and Workspace-side projects is presented in the Projects panel through a range of icons – note that the simple synchronization (mirroring) approach is available only when connected to an Altium 365 Workspace. The icons, and their meaning, are as follows:
||The local project and the mirrored project in the Workspace are synchronized.
Changes made to the local project are being synchronized to the mirrored project in the Workspace. For a local project not under external VCS, this occurs when saving a local file. For a local project under external VCS, this occurs when saving and committing local file changes to the external design repository.
||Project is Read-only
The project has been shared with you, but you have Read-only access to it. Under the Simple Sync methodology, the design project can be edited by a single person only (the owner of that project – the one who made it available online to the Workspace).
Changes have been made locally, but these have not been synchronized yet with the mirrored project in the Workspace. This can happen, for example, when the same project is open for editing by the owner/author on two computers (PC1 and PC2). On PC1, the Workspace is subsequently disconnected. On PC2, connection to the Workspace remains and changes are made. On saving the local file(s) the project remains unsynchronized. If you attempt to close the project on PC2, the Closing unsynchronized projects dialog will appear alerting you to this fact. If you choose to close the project, changes will not be available on PC1. To remedy the situation, disconnect from and then reconnect to, the Workspace on PC2. The project will be synchronized with the Workspace. The synchronized data will be reflected on PC1 once the Workspace is connected there too. Alternatively, right-click on the project and choose the Resolve Project Clone Conflict command. The Location of local projects has changed dialog will open. You will have the option to register the existing project as a New Project, where the data from the mirrored project in the Workspace will be used and local modifications will be lost, Move Project, where the data from the local project will be used and synced to overwrite the current data for the mirrored project in the Workspace, or Unregister, which unlinks the project and the data will not be sent to the Workspace.
There is a conflict between the data for the local project and the data for the mirrored project in the Workspace. This can happen, for example, when the same project is opened for editing by the owner/author on two computers (PC1 and PC2). On PC1, the project is opened and the Workspace is subsequently disconnected. Changes are then made and local files saved. Later, on PC2, the same project is opened and, while still connected to the Workspace, changes are made and saved. Later still, connection is made to the Workspace back on PC1. A conflict exists because there are changes locally on PC1, but the Workspace contains the updated data from changes made and synced on PC2.
To remedy the situation, on PC1 right-click on the project and choose the Resolve Conflicts command. The Resolve Conflicts dialog will open. You have the option to Use Server files (the data from the mirrored project in the Workspace will be used and local modifications will be lost), or Use Local files (the data from the local project will be used and synced to overwrite the current data for the mirrored project in the Workspace).
Limitations when using an Existing External Version Control Repository
As mentioned previously, your local designs may already be tracked under an existing, external version control system (Git, SVN, EPDM, etc...). When using an Altium 365 Workspace, you can continue using this setup as before and simply make the designs available to your Workspace by registering them with that Workspace – using the Make Project Available Online feature.
In this mode, every time you make changes to a design and commit those changes to your external VCS repository, that design data will be mirrored to the Workspace in the background, and all needed processing will be performed as usual – preview, where used, etc. There are some limitations to be aware of, however:
- Creation of a new design project still has to follow the previous flow, i.e. it is manually created in the external VCS system. The project is then registered and mirrored to the Workspace using the Make Project Available Online feature.
- If design changes are made but the commit/push is performed by external tools rather than through Altium Designer, then those changes will not appear for the mirrored project in the Workspace. This is corrected when the project is next reopened in Altium Designer, which automatically synchronizes the local project with the mirrored Workspace version. If the changes were made by another user, then the reopened project file(s) will show as
Out Of Date () and can be corrected using the version control Update command.
- Opening of the project by a second person will require access to that external VCS repository.
- Rights management will have to be set up/maintained in two places – in the Workspace and in the master source (the external Git/SVN/etc VCS repository).
- Some features delivered through the Altium 365 platform work only by having a project under the Workspace's native version control system. By keeping your project under an external version control system such features, as they become available to the platform, will not be available to you. You can move from using your external VCS to the Workspace's native VCS – see the following section for the procedure to achieve this.
Working with GitHub
Using the GitHub platform as an external version control system (VCS) is a popular way to host and share design projects, and Git repositories are supported by Altium Designer. As described above for an Altium 365 Workspace, the existing external VCS arrangement can be synchronized with (mirrored to) the Workspace, which allows you to benefit from its advanced data management and collaboration features.
How you normally work with GitHub itself will vary depending on company practices or simply the Git tools you have at hand. In general, however, a design project is created in a local Git repository and then Pushed to a GitHub (remote) repository, or an existing project is Cloned to a local repository from GitHub. Once in the local Git repository, the project can be opened in Altium Designer for editing – the software will recognize and use the local/remote GitHub repositories.
If the Git-based project is mirrored to an Altium 365 Workspace (Make Project Available Online), the project can be managed and worked within Altium Designer like any other project stored in the Workspace. In this arrangement, the Workspace still provides all the advantages of its project management system and also transparently communicates with GitHub to perform the major VCS actions – commit, push, pull, etc. Altium Designer will request your GitHub login credentials and retain these for subsequent GitHub interaction.
Note that Altium Designer is not able to connect with GitHub automatically if the GitHub account has been configured for two-factor authentication
While there is a range of data transfer protocols offered by the Git VCS, Altium Designer currently supports the HTTP/HTTPS protocol only for connections between a local Git repository and its remote master repository. In practice, the applied protocol is set by the URL prefix specified for the remote repository connection –
git://<remote repository>, and so on.
GitHub supports both the SSH and HTTPS protocols and recommends using HTTPS URLs for connections.
► See Which remote URL should I use? on GitHub for more information.
The HTTPS protocol offers the advantage of a secure connection that is simple to use and implement, whereas SSH is more complex to deal with – due to the need for public keys, and firewall/proxy port requirements – is arguably less secure, and does not provide the convenience of SSO (single sign-on) authentication.
Similarly, the GIT connection protocol is not recommended (or supported here) due to its lack of authentication and setup complexity.
If your external VCS system is bound to a protocol other than HTTPS, such as a GitHub SSH connection, this will be preset in a repository that has been cloned from the remote. As this protocol is incompatible with Altium Designer, an error will be thrown when attempting to integrate the project with an Altium Workspace. For the SSH connection, you will be offered to try to have that repository updated to use the supported HTTPS connection protocol instead (provided the repository itself supports this protocol). If you are unsure of the remote URL protocol that is used for a local Git repository, this can be checked using the
git remote – v command.
Use the Git Bash command line interface to check a repository's remote URL setting.
The repository can be reconfigured for a different URL, such as the HTTPS protocol to enable compatibility with Altium Designer, by using the
git remote set-url <name> <URL> command, where the URL's prefix specifies the protocol type.
Changing the remote repository connection URL protocol and then confirming with the remote command.
Moving from External VCS to Workspace Native VCS
When connected to an Altium 365 Workspace, Altium Designer also offers the ability to faithfully migrate projects that use an external VCS system to a fully-managed Workspace project that hosts the design files in its own Git repository. The converted design project, which will retain the previous history of VCS commits, can then benefit from the Workspace's native VCS-enabled features, such advanced project sharing, single authentication, and the event-based History timeline.
The project VCS migration feature supports both Git and SVN external version control systems and is available when making a local file-based project available online, or when promoting a mirrored (synchronized only) project to one under the Workspace's own Git VCS.
To simply migrate a project that is stored under external version control, right-click on the project name in the Projects panel and choose the Make Project Available Online option from the context menu, or select Project » Make Available Online from the main menu. In the following Make Available Online dialog, check the Migrate to Altium 365 Versioned Storage option and confirm the operation (OK).
The enabled Migrate to Altium 365 Versioned Storage option effectively causes the external VCS repository to be replaced with the Workspace Git repository, converts the project to one stored and managed in the Altium 365 Workspace, and where possible, brings across the version commit history from the external VCS. Note that If the migrate option is left unchecked, the project is mirrored to the Workspace (the Simple Sync arrangement) while maintaining the external repository as its VCS storage.
VCS migration is also available when Altium Designer is connected to an Enterprise Server Workspace. In this case, the Migrate to Altium Versioned Storage option is available in the Make Available On Server dialog. Note that If the migrate option is left unchecked, the project's external repository is maintained as its VCS storage (the Simple Sync arrangement is not supported for an Enterprise Server Workspace).
To port a local VCS project to a fully managed VCS project in your Altium 365 Workspace check the VCS migrate option when making it available online.
The Migrate Project dialog will open and warn you that the project is going to be migrated under full management of the Workspace's VCS. Click the Browse button to select a folder on your hard drive where a new (git-based) local project repository will be created. Click the Migrate button to proceed with the migration.
The Migrate Project dialog
After following the prompts, which includes making a final VCS commit, the project is now under version control in the Workspace Git repository. The external VCS commit history and its comment/messages are ported to the new Workspace VCS project, which can be accessed in the Altium Designer History view – right-click on the project name in the Projects panel and select the History & Version Control » Show Project History command.
When migrated, the project's external VCS commit history (shown on the left) is transferred to the Altium Designer History view (right).
Note that the first time you open Project History after the migration process you may see that data is being calculated for all included commits. The Workspace needs some time to process these commits and also the differences between them.
If the external VCS project is already managed in the Altium 365 Workspace as a mirrored project (synchronized local-server files), its VCS files can be migrated to the server's native Git repository using the Migrate to Altium Versioned Storage command, which is available from the Project History view, the Project Options dialog or the Projects panel's History & Version Control right-click context menu.
A VCS project that has been synchronized with (mirrored to) your Workspace is migrated using the Migrate Project to Altium Version Control option.
The migration performance is fastest when the source external VCS is Git-based – the process is simpler because the Altium 365 Workspace VCS is also Git-based. For SVN however, the migration can take some time depending on the size of the repository and the number of commits it contains.
VCS Migration limitations
- Git repositories that contain multiple PCB projects are supported when connected to an Altium 365 Workspace. After clicking OK in the Make Available Online dialog, you will be prompted to choose the files to migrate.
- The project file (
*.PrjPcb) should be located in the Git repository's root folder.
- The basic SVN
File protocol is not supported.
- If your SVN repository contains multiple projects, the migration process will create new local folders in addition to the existing SVN working copy. This is because the Altium 365 Workspace storage is Git-based, and a Git repository cannot be stored inside the SVN working copy.
- Commits that include an external file relative to the project folder may not be shown, since the migration process recognizes commits to the project folder only.
After successful migration of an external VCS project to the Altium 365 Workspace, the link to the external repository is removed automatically. This feature has been implemented in Altium Designer 23.0. If the project has been made available in the Altium 365 Workspace using a previous version of Altium Designer, an entry for the repository can appear on the Data Management - Design Repositories page
of the Preferences
dialog. If you are an administrator of the Workspace, and the repository has no reference to a Workspace project, the repository can be removed from the Workspace by selecting its entry and clicking the Remove
button. Note that if a project has been soft deleted (moved to Trash), it must be deleted permanently so the repository referencing it can be removed. The Workspace's
repository cannot be removed.
Collaboration after migration
- When a Workspace team member has migrated a project to Altium Versioned Storage, they need to ensure that other project collaborators connect to the team Workspace and then update their local (working) project copies. The latter is indicated in the Projects panel by the icon (Out of Date) associated with the project file and actioned by the Project » History & Version Control » Update Whole Project command.
- Once the migrated project has been updated, Altium Designer will offer to update the links to the new repository by rebuilding the project's local working folder. Choose the recommended option in the Fix version control link dialog to finish the local project update.
- Note that if a project collaborator does not connect to the team Workspace and then commits VCS design changes, these will continue to be registered with the external repository and therefore out of sync with the migrated Workspace VCS project.
- During migration, Altium Designer executes a commit to the original repository to set a notification mark so it can be recognized as having been migrated by other team members' instances of Altium Designer.
In some cases it may be desirable to manually migrate a project that uses an external VCS repository to one that is fully managed on an Altium Workspace and its native Git VCS repository. This can be done by creating a snapshot of your project, which disconnects it from external VCS and from the Workspace (if already made available there), and then making it available to the Workspace again, but under the Workspace's VCS – starting afresh as it were. To do so, follow the procedure below:
- Disconnect (remove) your project from the external version control system. This can be performed from your external interface tool to your current VCS, or through Altium Designer. In the case of the latter, while there are commands to remove the project from version control in both the Projects panel and the Storage Manager panel, the cleanest way is to use the Project Packager. Using the Project Packager will create a snapshot of your project, without the baggage of version control and, if you have previously made the project available to the Workspace, it will strip the links to the project in the Workspace.
If you have already made the project available to the Workspace, you'll want to unlink it as part of the packaging process. To do so, in the Managed Projects region on the Zip File Options page of the Project Packager wizard, make sure to enable the option to Unlink project from the server during packaging. This will ensure the link information to the mirrored project in the Workspace – which resides within the project file (*.PrjPcb) – is removed as part of the packaging process.
- Unpack your 'cleaned' project from the Zip archive created by the Project Packager.
- Open the project in Altium Designer – notice that it is neither managed (if it was previously) nor under version control. It is therefore a clean, unmanaged project.
- This next step is only if you had previously made the project available to the Workspace. The packaging process unlinked the project, but the mirrored project in the Workspace still remains untouched. You should delete the server-side project first. Access the Workspace's browser interface (through the Altium 365 Platform Interface). From the Projects page, click to select the project to be deleted, then click the control and choose the Delete command from the context menu.
Should you wish to keep the older version of the project in the Workspace, you should either rename it, or rename the fresh instance of the project when making it available online – whichever best suits your requirements.
- Now make the project available online again to the Workspace. To do this, right-click on its entry in the Projects panel and select Make Project Available Online from the context menu, giving access to the Make Available Online dialog. Make sure you enable the Enable Formal Version Control option, as this is what adds the project under the Workspace's own built-in VCS (Git).
As an alternative to the above step, the unpacked project snapshot (see step 2, above) can be directly uploaded to the Workspace using the New – Upload Project option
available in the Projects
view of the Workspace browser interface
. The resulting created project, available for opening in Altium Designer, is fully managed by the Workspace and its native VCS repository.
Note that the project essentially starts its history afresh – no previous version history is kept. By using the Project Packager, and taking a snapshot of your design at that point rather than removing the project from version control, you will retain the history of the previous VCS-linked project up to that point in time.
Controlling Project Synchronization
Once a local project has been made available to an Altium 365 Workspace, controls over its online availability and synchronization are provided through the General tab of the Project Options dialog.
Note that the General tab is presented only when Altium Designer is connected to an Altium 365 Workspace, rather than an Enterprise Server Workspace.
Options and controls relating to having made the project available online are presented on the General tab of the Project Options dialog.
Use the option available in the General region of the tab to make changes to the project description. This affects the mirrored project within the Workspace only.
In the Online Availability and Synchronization region of the tab, the Version Control option reflects the current style of online availability:
- Option Enabled – the project (and its source files) are stored under the Workspace's own native VCS (Git). This is the recommended approach, as by doing so you will have access to the maximum functionality offered through, and by, the Workspace and the Altium 365 platform.
- Option Disabled – the project files are stored in the Workspace for basic access and to enable sharing with others for viewing and commenting only – the Simple Sync arrangement.
Use the option to change between these two as desired.
This option is not available if the project is stored under an external VCS repository.
Should you wish to stop the synchronization between your local project, and the managed incarnation of it that was made available in the Workspace, click the button. The Turn off project synchronization window will appear. Click on the Unlink option, then click OK back in the Project Options dialog. The local project will no longer be associated with the project in the Workspace.
This is reflected in the Projects panel after saving the local project, by the project being presented under the active Project Group (*.DsnWrk), rather than as an entry under the active Workspace. A save is required since the links to the project in the Workspace are removed from the project file.
The project in the Workspace remains untouched – it is not removed by this action.
You can sever the connection between your local project and the incarnation of it made available in the Workspace.
You can always make the local project available online again, as a mirrored or full VCS project (Version Control). The General tab of the Project Options dialog will present the button, with which to access the Make Available Online dialog.
If you are making a local project available online again after having turned off synchronization, you may need to change the project name. Since turning off synchronization does not remove the project in the Workspace, this project, with the same name and folder location, may still exist. If you need to have the same project name, then the previous project instance in the Workspace can always be removed.
A local project can also be made available online – in the Workspace – from the General tab of the Project Options dialog.
Process-based Project Converting
Related pages: Designing Collaboratively, Creating and Managing Processes (Altium 365 Workspace, Enterprise Server Workspace).
The functionality described in this section is only available when using Altium Designer with active Altium Designer Enterprise Subscription and a connected Workspace.
When the connected Workspace includes activated process definitions that are part of the Project Creations theme, the indexed commands can be accessed by right-clicking on an unmanaged project in the Projects panel, clicking Convert to Managed Project, then selecting the desired process from the sub-menu.
If no active process definitions are available for the Project Creations process theme - in your active Workspace - the sub-menus will not be visible.
After launching the command, the Create Project dialog (actually named after the chosen process) opens. Use the General tab of the dialog to describe the project and specify the type of project and template, if desired. On the Advanced tab, you can specify the location of the project and choose the repository, and repository and Workspace folders. Once ready, click Start to create the new Workspace project in accordance with the underlying workflow for that process.