Git Security Overview

This guide explains how Capable integrates with Git providers in Confluence, how authentication works, how multiple accounts are handled, and what viewers see if they don’t have access to a referenced repository or file.

#Authentication model (per-user, least privilege)

Per-user OAuth: Each user authenticates directly with their Git provider via the Atlassian Forge OAuth2 provider. Access tokens are stored and managed by Atlassian on a per-user basis; they are not shared across users.
No shared or service tokens: The app never uses a global token to bypass Git permissions. All content browsing and file fetching is performed with the currently signed-in user’s token.
Scopes (GitHub in Confluence): The app requests repo, user:email, read:org, and read:user. These scopes enable repository listing and file reads, including private repos the user already has rights to.
Network access: Requests are routed only to the approved Git endpoints (e.g., api.github.com, raw.githubusercontent.com).

#Multiple accounts per provider

Users can connect multiple accounts (e.g., personal and work GitHub) and switch which account to use in the browser modal.
- Confluence: account selection is limited to GitHub.
- Jira: account selection supports GitHub, GitLab, and Bitbucket.
The selected account determines which token is used for repository listing and file content retrieval.

#Organization access and admin prerequisites (GitHub)

If your GitHub organization enforces SSO or app approvals, an org owner/admin must approve access for the Capable app first.
After org approval, each user still authenticates individually and must be a member with permission to the target repo.
If an org requires SSO re-authorization per user, users must complete that flow when prompted by GitHub during sign-in.

#What happens when viewing a page with a Git macro

The macro stores a reference to the repo path (and, in Confluence, also the GitHub account context used during configuration).
When a viewer opens the page:
- The app attempts to fetch the content using the viewer’s own authenticated session and selected/associated account.
- If the viewer has access, the content renders normally (markdown, diagrams, images, or code with syntax highlighting).
- If the viewer is not authenticated, they’ll be prompted to connect their Git account.
- If the viewer is authenticated but lacks repo access, the content will not render; the UI will display an authorization or access error. The page still loads; only the macro’s content is restricted.

#User-by-user permissions

Every user must sign in with their own account. A page author’s access does not grant access to other viewers.
The app respects provider-side permissions: private repos only render for users who already have rights in Git.

#Data handling and privacy

Tokens are handled by Atlassian Forge’s auth provider per user and are not shared with other users.
The app only calls the Git provider APIs and raw file endpoints declared in git-conf.yml.
The app does not persist raw Git content beyond what’s needed to render in the current session.

#Troubleshooting

I’m asked to connect even though I have access: Sign in with the correct account (work vs personal) and ensure it’s selected in the modal.
Org repositories don’t appear: Ask an org owner to approve the app/SSO for your organization. Then sign in again.
Macro shows an access error: You may not have rights to the specific repo/path or branch referenced by the macro. Request access from the repo owner, then refresh.