Using GitHub Diagrams

Connecting with GitHub

The add-on needs to access the GitHub repository. Instructions on how to enable access are in the link below.

https://stratus-addons.atlassian.net/wiki/spaces/PDFC/pages/1733689350

Repository Explorer

After GitHub account has been connected with PlantUML OAuth application you will be able to access repository data using the GitHub Repository Explorer (GRE).

GitHub Repository Explorer

Click on the Octocat icon on the toolbar and the GRE will open in a popup window. It will list all repositories visible to the GitHub user.

Octocat icon opens GRE

Double-click the repository name and you will be presented with all branches from that repository.

Selecting a branch will lead user to files and folders stored under that branch. Double click on the file you wish to open. The PlantUML editor can open most text files, but will reject other formats. User's responsibility is to provide valid PlantUML syntax to the editor. Invalid file will simply lead to error in generating diagram preview.

User cannot edit GitHub files in the editor. Add-on uses only read access calls when accessing repository data. Note that GitHub automatically grants Read and Write access to all OAuth applications. Add-on does not use write access and you can further restrict account access in your GitHub settings.

When file is updated in the repository, the add-on will generate new preview after detecting the change. This is done when opening page containing PlantUML diagrams.

Updating diagram with the new version from the GitHub

If you disconnect account from the GitHub app, imported diagrams will stop updating but will be visible on the pages. Latest version before disconnecting account will be shown. Also, when file is deleted on GitHub, the add-on will still show last version before deletion. In both cases there will be tooltip with error describing problem with GitHub.

Tooltip with diagram location