Using GitHub Diagrams
Connecting with GitHub
The app needs to be allowed read access to the GitHub repository. Please have a look at Connect with GitHub in order to enable it.
Repository Explorer
After GitHub account has been connected with PlantUML OAuth application, users will be able to access repository data using the Import from GitHub option.
Clicking the Octocat icon will open the GitHub Repository Explorer (GRE) in a popup window. User can select repository from the drop-down menu or use search functionality.
After selecting repository and branch user will see list of folders and files. Clicking on a file will open file content in the bottom popup area.
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 have write access and users may further restrict permissions in their 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 user disconnects their 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 the GitHub repository, 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, users 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, users should open GitHub and navigate to the file they wish to include on a Confluence page. Copy the file’s URL from the 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.