> For the complete documentation index, see [llms.txt](https://docs.cipp.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cipp.app/user-documentation/cipp/integrations/github.md). # GitHub The GitHub integration lets CIPP work with GitHub repositories, most visibly through the Community Repositories catalog where templates and scripts are browsed, imported, and published. Authentication uses a GitHub Personal Access Token, and the scopes you grant determine how much of the functionality is available. {% hint style="info" %} The integration is optional. Without it, CIPP falls back to a built-in shared token that provides read-only access to public community repositories. Configure your own token when you need private or internal repositories, or when you want to publish templates and scripts back to GitHub. {% endhint %} ## Settings | Setting | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable Integration | Turns the integration on, so that CIPP authenticates as your token rather than falling back to the shared read-only one. The token field and the **Test** button remain unavailable until this is enabled and saved. | | GitHub Personal Access Token | Your GitHub Personal Access Token. Stored securely and masked once saved. | ## Choosing the Right Token Scopes Grant the narrowest scope that covers what you intend to do. | Scope | What it covers | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `repo:public_repo` | The minimum required. Reading and writing public repositories, which is enough for browsing and importing from public community repositories. | | `repo` (full) | Required for private and internal repositories, and for publishing your own templates and scripts back to GitHub. | {% hint style="warning" %} Use a classic Personal Access Token rather than a fine-grained one. Fine-grained tokens scope permissions differently, and that difference causes unexpected failures against the endpoints CIPP uses. The **Test** button reports when it detects a fine-grained token, because it cannot read back the granted scopes in that case. {% endhint %} See [GitHub's documentation](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) for how to create a token and what each scope grants. ## Configuring the Integration {% stepper %} {% step %} ### Create the token Create a classic Personal Access Token in your GitHub account settings, granting the scopes described above. Copy it before leaving the page, as GitHub will not show it again. {% endstep %} {% step %} ### Enable the integration Turn on **Enable Integration**. The token field stays disabled until it is on. {% endstep %} {% step %} ### Enter the token Paste the token into **GitHub Personal Access Token**, then select **Submit** and wait for confirmation that the settings were updated. {% endstep %} {% step %} ### Test Select **Test**. A successful result names the GitHub account CIPP authenticated as, and lists the scopes attached to the token, so you can confirm at a glance whether you have granted enough for what you plan to do. If GitHub rejects the token, the result says so and repeats the reason GitHub gave, so an expired or revoked token is obvious here rather than appearing to work. {% endstep %} {% endstepper %} ## When the Token Stops Working Personal Access Tokens expire, get revoked, and run into rate limits. When GitHub rejects the token you configured, CIPP falls back to the built-in shared token for anything that only reads, so browsing and importing from public community repositories carry on working. Anything that writes, such as publishing a template or creating a repository, keeps failing until the token is replaced. Every rejection is written to the [Logbook](/user-documentation/cipp/logs.md) as a **GitHub** entry naming the status GitHub returned, so a token that has quietly expired shows up there before anyone reports a failure. {% hint style="info" %} **Test** is the exception to the fallback. It always reports on the token you configured, never on the shared one, so it stays a reliable check on the token even while reads are quietly succeeding through the fallback. {% endhint %} ## What the Integration Enables | Capability | Token requirement | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Browsing and searching community repositories | None. Works through the built-in shared token. | | Importing templates and scripts from a public repository | None, though your own token gives you a higher rate limit. | | Adding a private or internal repository to the catalog | Full `repo` scope. | | Publishing templates and scripts to a repository | Full `repo` scope. | | Creating a new repository from CIPP | Full `repo` scope, on a token belonging to an account with rights to create repositories in the target user or organisation. | Repositories and their templates are managed on the [Catalog](/user-documentation/tools/community-repos.md) page rather than here. This page only holds the credentials. ## Reading the Results Banner Results from **Test** appear in a banner at the top of the page, with two controls common to all integration pages. | Control | Description | | ---------------- | --------------------------------------------------------------------- | | View Results | Opens a table showing the results of the most recent attempt in full. | | Download Results | Downloads those results as a CSV file. | *** ## Feature Requests / Ideas We value your feedback and ideas. Please raise any [feature requests](https://github.com/CyberDrain/CIPP/issues/new?template=feature.yml) on GitHub. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cipp.app/user-documentation/cipp/integrations/github.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.