> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cymph.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Import playbooks from GitHub repositories and commit playbook backups back to them.

## What Cymph uses it for

Cymph uses GitHub for three purposes, all driven by a **single access token**:

1. **Fetching playbooks / content** — reads repositories, branches, and files to import playbooks and other content into Cymph. *(read)*
2. **Backups** — commits playbook backups into a repository on a schedule or on demand. *(write)* See [Back up playbooks to GitHub](/how-tos/github-backup).
3. **Publishing documentation** — commits a playbook's documentation into a repository as Markdown or PDF. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks).

A single token can serve any combination of these depending on which repositories you point Cymph at. Cymph connects to `github.com` (no instance URL field).

Because the `repo` scope is required in all cases (see below), publishing needs **no additional permissions** beyond what the integration already asks for.

## Requirements

| Field     | Description                                          |
| --------- | ---------------------------------------------------- |
| **Token** | A GitHub personal access token with the `repo` scope |

## Token setup

Create a token with the required scope using this pre-filled link:

👉 [Create a Cymph integration token](https://github.com/settings/tokens/new?description=Cymph%20integration\&scopes=repo)

This grants the **`repo`** scope, which covers both read (fetching playbooks) and write (committing backups) on private repositories.

<Note>
  Cymph verifies that the token carries the `repo` scope when you save the integration and will reject tokens that do not have it, even if you only intend to use the read (fetch) functionality. This is required so that private repositories are accessible and backups can be committed.
</Note>

If you use a **fine-grained personal access token** instead, grant it **Contents: Read and write** on the target repositories.

## Permissions

| Scope  | Why Cymph needs it                                                                             |
| ------ | ---------------------------------------------------------------------------------------------- |
| `repo` | Read repository contents, branches, and files; commit backup files and published documentation |

## What Cymph reads and writes

## Publishing formats

GitHub accepts both documentation formats:

| Format          | What it contains                                                                  |
| --------------- | --------------------------------------------------------------------------------- |
| **Markdown**    | The playbook's documentation blocks, rendered as Markdown                         |
| **Summary PDF** | The full playbook summary report — metadata, contributors, and the workflow image |

Image blocks are omitted from the Markdown format.

## Testing the connection

Cymph validates the connection by listing the authenticated user's repositories.