Using GitHub Diagrams
- Aljoša Klišanić
- Boris
- Boris Jockov
Connecting with GitHub
The add-on needs to access the GitHub repository. Instructions on how to enable access are in the link below.
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-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.
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.
Repository URL feature
In order to avoid browsing repositories user can directly put repositoru URL into “GitHub repository URL” field. It should be in standard format received from “Clone from HTTPS“ feature 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
User can always choose direct link feature to avoid navigating through the repositories.
Open GitHub and navigate to the file you wish to include into Confluence page. Copy URL from the browser. Paste that URL into upper right field in Repository Explorer:
If the URL is valid it will enable “Select” button. Click on the button and the diagram will be loaded into editor.