> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-github-integration.md).

# How to set up the GitHub integration

Connect GitHub so your team can link issues to the journey-map steps they affect.

An Admin connects GitHub once at the account level. After that, anyone in your workspace can search GitHub and link issues to planning cards on any journey map.

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Set up the GitHub integration](#set-up-the-github-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use GitHub in planning cards](#use-github-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the GitHub integration

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* A GitHub account with access to the repositories whose issues you want to link.
  {% endhint %}

GitHub uses a single authentication method: the name of the organization or user that owns the repositories, plus a fine-grained personal access token created for that owner.

{% stepper %}
{% step %}
**Open the GitHub integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **GitHub** in the **Planning integrations** list.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-710c74fcff0989d65fc45630335bdef67f16fc32%2Fintegrations-github-01-integrations-tab-crop.png?alt=media" alt="The Planning integrations section of the Integrations tab in Smaply Account settings. Jira, Azure DevOps, Asana, Linear, Trello, Monday.com, and GitHub are listed, each with an Edit or Set up button. GitHub, the last row, shows Set up."><figcaption><p>GitHub in the Planning integrations list</p></figcaption></figure>

The **Configure GitHub** page opens with two empty fields and a blue help block summarising the setup.

<figure><img src="https://1197101183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2Fgit-blob-675051b276253b0b0bff47069e45b18dad563b5b%2Fintegrations-github-02-setup-empty.png?alt=media" alt="The Configure GitHub page in Smaply. A GitHub API Configuration form has a blue help block with three setup steps, two empty required fields labelled Organization or user name and Personal access token, and a Save Configuration button."><figcaption><p>Configure GitHub, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create a fine-grained personal access token in GitHub**

Click the **github.com/settings/personal-access-tokens** link in the help block. It opens GitHub's new fine-grained token form in a new tab. Sign in if asked. You can also get there from your GitHub profile picture via **Settings > Developer settings > Personal access tokens > Fine-grained tokens > Generate new token**.

Fill in the form:

* **Token name** - Something you'll recognise later, such as `smaply-connector`.
* **Expiration** - When the token stops working. Smaply's connection stops at the same time, so note the date.
* **Resource owner** - The organization or user that owns the repositories you want to link.
* **Repository access** - Choose **Only select repositories** and pick the repositories in **Selected repositories**.
* **Permissions** - Set **Issues** and **Metadata** to read-only.

Click **Generate token** and copy the token.
{% endstep %}

{% step %}
**Enter your details and save**

Back on the **Configure GitHub** page, enter the owner's name in **Organization or user name**. Use the name as it appears in the GitHub URL, for example `octo-org` from `github.com/octo-org`, and make sure it matches the **Resource owner** you picked for the token. Paste the token into **Personal access token** and click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows a green confirmation. GitHub is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure GitHub** page from **Account Settings > Integrations**, where the GitHub row now shows **Edit**. A connected integration shows your organization or user name and a masked token, with a green confirmation that you're connected to GitHub. From here you can also **Edit Configuration** or **Delete Configuration**.

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use GitHub in planning cards

Once GitHub is connected, anyone in your workspace can add a planning card to a journey map, pick GitHub in **Search planning items**, and link the issue it relates to. The integration links issues, not pull requests. For the full flow, see [How to use planning cards](https://helpdesk.smaply.app/journey-maps/cards/how-to-use-planning-cards.md).

***

#### Troubleshooting

The **Configure GitHub** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The owner name or token is wrong, or they don't belong together. Reopen **Configure GitHub**, click **Edit Configuration**, and check each value:

* **Organization or user name** is only the name, such as `octo-org`, not the full URL.
* It's the same owner you picked as **Resource owner** when you created the token.
* The token is pasted in full, with no extra spaces.

Save again. If it still fails, create a fresh token and enter it.

</details>

<details>

<summary><strong>Your organization isn't offered as Resource owner in GitHub</strong> - Organization policy</summary>

Your GitHub organization has blocked fine-grained personal access tokens, so it doesn't appear in the **Resource owner** list. Ask a GitHub organization owner to allow fine-grained tokens, then create the token again.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but GitHub returns nothing for your search. Check these in order:

* The token may still be pending approval. Some organizations require an organization owner to approve fine-grained tokens. Until then, the token can only read public repositories, so issues in private repositories won't appear. Ask an organization owner to approve it.
* The repository may not be selected. The token only sees the repositories you chose under **Repository access**. Edit the token in GitHub to add the repository.
* The permissions may be missing. The token needs read-only access to **Issues** and **Metadata**.
* You may be searching for a pull request. The integration links GitHub issues only.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token expired or revoked</summary>

A working GitHub connection breaks when the token expires, is deleted in GitHub, or the person who created it loses access to the repositories. Your organization may also limit how long tokens can last.

Create a new token at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new), then reopen **Configure GitHub**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>Issues are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which GitHub issues appear, the connection uses the token's access. If a teammate can't find an issue they can open in GitHub, its repository may not be among those the token covers.

</details>

For questions about how the connection behaves across your account, such as disconnecting GitHub or what happens when you remove it, see [How to manage integrations](https://helpdesk.smaply.app/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="https://helpdesk.smaply.app/integrations/how-to-manage-integrations-at-account-level.md">Manage integrations</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link issues from connected tools onto a journey map</td><td><a href="https://helpdesk.smaply.app/journey-maps/cards/how-to-use-planning-cards.md">Planning cards</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="https://helpdesk.smaply.app/integrations/set-up-your-first-integration.md">Set up first integration</a></td></tr></tbody></table>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-github-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
