A newbie's guide to configuring source control for Archi using coArchi.
The repository contains the Archimate architecture landscape models built using Archi.
Below are detailed instructions on installing and configuring Archimate, the coArchi plugin and integrating with Github.
Request Git CLI installation from your IT support team, or download it from https://gitforwindows.org/
Once installed, it is required that you disable SSL verification due to a limitation of the coArchi plugin. Make the following configuration changes under C:\Users[username].gitconfig :
[https]
sslVerify = false
[http]
sslVerify = false
Download and install the latest version of Archi from https://www.archimatetool.com/download/
From https://www.archimatetool.com/plugins/ download the most recent version of coArchi.
To install the plug-in, open Archi and install from the application menu: Help > Manage Plug-ins:
Click [Install New ...] and select the downloaded plug-in file. You may need to restart Archi to activate the plug-in. Please ensure the plug-in version supports the installed version of Archi.
If your plug-in installation was successful, the [Collaboration] menu item will appear on the application menu after restarting Archi.
To configure Archi for Github integration you would need to create a Personal Access Token (PAT) from your user account. For a detailed overview of the process you can visit https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
Alternatively, you can follow the steps below:
- Log onto your Github account
- Select [Settings] from your account menu (look for the avatar at the right-top of the page)
- Select [Developer settings] from the menu on the left-hand of the page
- Select [Personal access tokens] and then [Tokens (classic)]
- Select [Generate new token] and then [Generate new token (classic)]
- Enter your token name, set the token expiry and select the [repo] scope for the token
- Click [Generate token]
- Copy the token from the screen and store it securely for configuration purposes. IMPORTANT: YOU CANNOT RETRIEVE THE TOKEN AFTER IT HAS BEEN GENERATED AND DISPLAYED ON THIS PAGE. IF YOU LOOSE IT YOU WILL NEED TO GENERATE A NEW TOKEN.
Once you have configured Archi and coArchi, and generated your PAT you will be able to import the Archimate model into the modeller.
From the Collaboration menu, select [Import Remote Model to Workspace]. You may need to provide Archi a master password to unlock this feature.
In the Add Remote Model modal, provide the following information:
| Field | Description |
|---|---|
| URL | The full web URL of the repo: https://github.com/username/reponame.git |
| User Name | Your Github user name |
| Password | The PAT you generated earlier |
It is possible that you could use your credentials as-is in the screen. However, it is recommended that you enable 2FA on your Github account to protect access to the repo. In this case you will only be able to log onto Github from Archi using the PAT.
To obtain the repo URL, you can copy of from the Clone address:
From the Collaboration menu, select [Toggle Collaboration Workspace] and [Toggle Branches View]. The Workspace and Branch windows will be docked within Archi. Archi/coArchi supports repository branches.
The Collaboration Workspace is used to navigate between different models and individual branches checked out while the Branches View provide the ability to manipulate branches within the selected model.
It is recommended to refresh the model from Github prior to making any changes. Regular refreshes also help to keep local repo copies updated with changes made to the upstream repository. It is important to refresh the model prior to committing any changes to avoid overwriting upstream changes made since the local repo copy was pulled from the server.
To refresh your local copy of the model, open the model / branch from the Collaboration Workspace and select [Refresh Model] from the [Collaboration] application menu.
To protect the integrity of the main branch and avoid overwriting updates from oneanother, it is recommended to create a branch for each piece of work. Branches could be named by initials, date or subdomain. Branches can be created either through the coArchi plugin or online on Github.
[Add branch] will create a local branch while [Add branch and checkout] will create the local branch and set it as the active branch. Neither of these actions will create the upstream branch (on Github server).
By committing changes you create a local snapshot of the repository into a single package. This does not upload the changes to the upstream branch, but create a local packaged copy. To commit your latest changes, select [Commit changes] from the Collaboration menu.
The final step is to publish the committed package back to the repository. This will insert the last committed package into the upstream branch.
On regular intervals all committed and published branches need to be merged into the main branch which will trickle down into all subsequent branches.
For more information on the mechanics and command line (CLI) operations, you can read the following documents: