| Note |
|---|
Support for Atlassian Server Products is ending in February 2024. Consider migrating to Github Macros for Confluence’s Data Center version. Or, are you planning to migrate to Cloud? Make sure you do not lose your data/configurations in the process. Check out the Migration guide for information on how to migrate the app’s data to Cloud. Contact our support team if you have any questions. |
Macro to include code snippets, files, issues
...
and more from Github into Confluence
Features
- Include and render markdown files from Github into Confluence.
- Include issue lists from Github into Confluence.
- Include pull request lists from Github into Confluence.
- Support for both private and public repositories.
Configuration
| Info |
|---|
You'll need a personal access token from Github to configure the plugin for the server. To create a personal access token, go to this link. NB: While generating the access token, please make sure the required and respective parameters are selected. So, for example, if you have private repositories, then you will have to define the scope of the access while generating the token by selecting the respective scope 'repo Full control of private repositories', like shown in the image below:
|
...
| Table of Contents | ||||
|---|---|---|---|---|
|
| Note |
|---|
Once a Github token is configured, all confluence users will have access to it when using the macros. This means that contents of private repositories will be accessible to all Confluence users. |
If enabled, macro use tokens with Github API to render private images and links in Markdown from your private Github repositories. Note, that Github has a limit for API calls, so if your page with Github Macro has thousands of views, you may exceed the hourly API call limit of your token.
Register new personal access token
| Info |
|---|
You will need a personal access token from Github to configure the plugin for server. Create a personal access token here. |
Once you have obtained a personal access token click the Add new token button on the plugin configuration page.
You'll be presented with a 
A configuration dialog appears. Enter your username and personal access token here. If you 're are using Github Enterprise, you can also add the optional URL for your own Github server. Once you 're done click the Add button.
Use tokens to resolve images and links in Markdown files
Also, you can select whether to use tokens when resolving images and links in Markdown files. This allows to render images from private repositories properly when you view or export page, for any authenticated user.
Note, that separate Github API call is used to resolve image or link Github url in this case. Since Github has a hour limits for API calls, this may be undesired: if you rich limit, content from private repos won't be resolved until end of rate limit period. In this case just un-check this option (saved automatically in background), and tokens will be used to fetch the content of private Markdown files only.
You're now ready to use the macro!
Available Macros
- Github Pull Request List
- Github Issue List
- Github Markdown File
- Github File Content
Here is an example of the Github Pull Request List macro filled out. We used a public repository so you can copy the values if you want to try it out for yourselves.
Using the Macro
To use the macro, select your token from the dropdown, and add the username or organization name for the repository you want to pull information from.
Pull requests and issues have a query field. You can use Github's Query language to select pull requests or issues you want to displayare done, click Add.
Limit the number of lines (Optional)
If you want to display only certain lines of code, specify the limit of the code lines to be displayed. Leave this parameter blank to display complete code lines. Or, you can specify range or number of maximum lines to be displayed. For example: 5, 2-25.
| Info |
|---|
|
You are now ready to get started with the macro!
Refer to the Macros page to learn more about the macros.