Using GitHub Diagrams
Connecting with GitHub
The app needs to be allowed to access the GitHub repository. Please have a look at https://stratus-addons.atlassian.net/wiki/spaces/PDFC/pages/1733689350 in order to enable it.
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).
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.
Double-clicking the repository name displays all branches associated with that repository.
After selecting a branch, the files and folders contained within it will be shown. Double-click any file you wish to open. The PlantUML editor supports most text-based formats but will reject unsupported file types. Users are responsible for ensuring that the file contains valid PlantUML syntax; invalid content will result in an error during diagram preview generation.
Users cannot modify GitHub files from within the editor. The app utilizes read-only access when retrieving repository data. Note that GitHub automatically grants both read and write permissions to OAuth applications; however, the app does not make use of write access, and you may further restrict permissions in your GitHub account settings.
When a file is updated in the repository, the app generates a new preview once the change is detected. This detection occurs when a Confluence page containing PlantUML diagrams is opened.
If you disconnect your account from the GitHub app, previously imported diagrams will no longer receive updates; however, they will remain visible on their respective Confluence pages. The final version retrieved before the account was disconnected will continue to be displayed.
Likewise, if a file is deleted in GitHub, the app will continue to show the most recently retrieved version of that file.
In both situations, a tooltip will appear indicating that an error occurred while attempting to communicate with GitHub.
Repository URL feature
To avoid manually browsing through repositories, the user may enter the repository URL directly into the GitHub repository URL field. The URL must follow the standard format provided by the Clone with HTTPS option on the GitHub project page.
When user provides this URL he will be automatically redirected to given project Branches view. If URL is invalid error message is shown.
Direct link feature
Users may also choose to use the direct link feature to avoid navigating through repositories.
To do so, open GitHub and navigate to the file you wish to include on a Confluence page. Copy the file’s URL from your browser and paste it into the field located in the upper-right corner of the Repository Explorer.
If the URL is valid it will enable “Select” button. Click on the button and the diagram will be loaded into editor.