# Embed a GitHub file in Confluence

To embed a GitHub file in Confluence, add the **Github file (Capable)** macro to the page, connect your GitHub account, then pick the repository and file and select **Add to page**. Or paste the file's GitHub link straight into the editor. The file stays live: code is highlighted, Markdown is formatted and diagrams are drawn.

---

## Before you start

| **You need**                                    | **Why**                                                                                                                                                                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Permission to edit the page                     | The macro is added in the Confluence editor.                                                                                                                                                                       |
| A GitHub account that can read the repository   | The picker lists only repositories your connected accounts can see. A public file pasted as a link needs no connection.                                                                                            |
| Readers of a private file need their own access | Each reader connects their own GitHub account. Nobody borrows yours. See [Private file path](https://help.gocapable.com/git/private-file-path.html). |

---

## Steps

1. Open the Confluence page and select **Edit**.
2. Type **/Github** and choose **Github file (Capable)**.
3. On the macro, select **Select File** to open the **Browse Git Repositories** window.
4. If you have not connected GitHub yet, select **Connect** and authorise the app in the GitHub window that opens.
5. Type part of a repository name in **Search repositories or paste URL...**, or paste a GitHub file link and press Enter.
6. Open the repository, go into folders until you see the file, and select it to preview it.
7. Select **Add to page**, then publish the page.

📝

**Quicker:** paste a github.com `/blob/` link or a raw.githubusercontent.com link into the editor and it turns into the macro by itself, with the repository, branch and path taken from the link. See [Auto-convert pasted GitHub links](https://help.gocapable.com/git/auto-convert-pasted-github-links.html).

---

## What happens next

The file appears under a header showing `owner/repo/path`. The branch shows in brackets when it is not `main`. Readers can select **Open on GitHub** to jump to the file, and signed-in readers get **Refresh content**. The page byline counts the files, for example **1 file**.

The macro reads the file from GitHub every time the page is viewed, so it always shows what is on the branch now. There is nothing to sync.

---

## If it does not work

* The macro asks readers to **Connect GitHub**: the file is private and that reader has no connected account with access. See [Readers see "Connect a GitHub account with access to this repository to view this file"](https://help.gocapable.com/git/readers-see-connect-a-github-account-with-access-to-this-repository-to-view-this-file.html).
* The picker says **This file type cannot be rendered**: the file type is not supported, for example a PDF or a zip file.
* A pasted link stayed a link: see [Pasted a GitHub URL and it did not turn into a macro](https://help.gocapable.com/git/pasted-a-github-url-and-it-did-not-turn-into-a-macro.html).

---

## Related

### [Github file](https://help.gocapable.com/git/github-file.html)

Every setting and what the macro shows.

### [Auto-convert pasted GitHub links](https://help.gocapable.com/git/auto-convert-pasted-github-links.html)

Paste a link, get the macro.

### [Connect your GitHub account to Confluence](https://help.gocapable.com/git/connect-your-github-account-to-confluence.html)

Link your GitHub account first.

### [Show a GitHub README in Confluence](https://help.gocapable.com/git/show-a-github-readme-in-confluence.html)

The same, for a README.

### [Troubleshooting](https://help.gocapable.com/git/troubleshooting.html)

When the file does not show.

---

_One macro, the file as it is today._