# 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)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)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)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)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)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)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)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.