# Connect GitHub with a personal access token

Connect GitHub to Neo.Tax with a personal access token.

To connect Github to Neotax, there are two main steps. 

You’ll start by creating a personal access token from Github with the necessary permissions. Then you’ll connect that token to NeoTax. The instructions below will guide you through this step by step.

#### **Part 1: Create the Personal Access Token**

**Step 1**: In the upper-right corner of any page, click your profile photo, then click **Settings**.

![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/9a714459-3628-432e-9a8a-f769c8dc8526/github-token-1.png)

**Step 2**: In the left sidebar, click  **Developer settings**.

![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/d199791c-a8c0-490d-bdec-7d3883815556/github-token-2.png)

**Step 3**: In the left sidebar, under  **Personal access tokens**, click **Fine-grained tokens**.  Then click **Generate new token** at the top right of screen.

![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/f60a9078-8201-4f96-98dd-ed3068c93341/github-token-3.png)

**Step 4: Configure Token**

**A. Under Token name, enter a name for the token.  You should put a name that helps you remember how this token is being used (ex.,** **`neo-tax-integration`****).**

![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/eb705245-3010-4ffa-a1d8-88be0190ee54/github-token-4.png)

**B. Under Resource owner, change the dropdown to your organization name.** 

It defaults to your user, so you have to actively change it to the organization.

> **Warning:** **This is the most common cause of a failed connection.** The *Resource owner* must be your **organization**, not your personal account. If you leave it set to your user, the connection may look like it succeeded but will silently fail to link your organization — and no data will sync.

Note, below we show `neo-tax` as an example of an organization.  Your organization should have your organization’s name.

![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/84c9998d-ff5d-4839-8fda-3f069b3be195/github-token-5.png)

Before proceeding, double check that you have changed the owner to the correct organization.

C. Under **Repository access**, select which repositories you want the token to access. You should choose the minimal repository access needed.  

1. The simplest solution is to select **All repositories**.  
1. If you choose **Only select repositories**, then select the individual repositories that you want the token to access.

![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/5e5a4317-b45d-4980-8924-d1e7dbb53bf8/github-token-6.png)

D. Under **Permissions**, select the following:

![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/a4dae1d1-94c8-47f0-acb9-c4a23c677388/github-token-7.png)

**E. If you are NOT an owner/admin of the GitHub organization > confirm the Owner has approved your token.** 

> **Warning:** When a non-admin creates an organization-scoped token, GitHub holds it in a *pending* state, and the Neo.Tax connection will fail to set your organization until an owner approves it. **Do this before starting Part 2.**
>
> An organization owner/admin approves the request by:
>
> 1. Go to “Your Organizations” from the top-right menu
> 1. Select the organization
> 1. In the left-hand menu, under the “Third-party Access” section, select “Pending requests”
> 1. Approve the request

> **Tip:** For customers using GitHub Enterprise, the fine-grained PAT may not provide the work emails for all of the users in your GitHub organization. If it does not work, the alternative solution is to link a Classic PAT, using the instructions from this link: [https://help.merge.dev/en/articles/8562560-github-how-do-i-link-my-account](https://help.merge.dev/en/articles/8562560-github-how-do-i-link-my-account)

#### **Part 2: Connect the token to** **Neo.Tax**

1. Login to [https://app.neo.tax](https://beta.app.neo.tax/)
1. Go to the `Projects` page and click `Connect Project Management` > `GitHub Issues`. 

   ![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/50230568-c30c-4923-a989-de72ca6b537a/github-token-8.png)
1. When prompted, enter your personal GitHub **username** as the `User ID`. This only identifies *who you are* — it does **not** change what the token can access; the token itself must still be scoped to your **organization** (Part 1, Step 4B). Then enter the **personal access token** you created. We use that limited-access token to connect.

   1. Note, the example below shows the a representative GitHub user, you should enter your own  `User ID`.

   ![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/968fee57-3251-4642-b8ee-8e2ab7b0ae02/github-token-9.png)
1. Only then do you enter your Github organization name.  

   1. Note, the example below shows `neo-tax` but you would enter your organizations name.

   ![Screenshot from Connect GitHub with a personal access token](https://vaffozzswoq4jjsz.public.blob.vercel-storage.com/help-center/93eb6192-fa29-4be8-a3ef-144ff78c9187/github-token-10.png)

#### Mapping Github to Payroll

**To match to payroll data, you’ll then need to create a mapping of GitHub user IDs to Work Emails.**

1. Create a CSV with *GitHub UserId*, *Work email*
1. Upload to Neo.Tax > Data Sources > Tax Documents

#### **FAQ**

**Q: I finished both parts, but nothing is syncing / I was told the organization didn’t get set.**

A: This means the token didn’t resolve to a single GitHub organization. Check, in order:

1. The token’s *Resource owner* is your **organization**, not your personal user (Part 1, Step 4B). This is the most common cause.
1. If you are not an org admin, your token request was **approved** by an owner under *Third-party Access → Pending requests* (see the Part 1 callout).
1. You belong to **only one** GitHub organization. If you’re a member of several, the connection can’t tell which one to use — contact your Neo.Tax implementation team and we’ll set it manually.

**Q: How does** **Neo.Tax** **use GitHub data?**

A: We use the GitHub *pull requests* as the primary object. Each pull request is treated as a task or ticket done by a specific person and then grouped intelligently into projects by our AI system. We use the changelog of the pull request to identify when the work was done.

Each repository is treated as a team and we generate projects grouped by repository.

**Q: Do I need to use GitHub Issues?**

A: No. The system works off of *pull requests* in GitHub. As long as your team uses pull requests, which nearly all teams do, the data should work.

**Q: Does this look at my source code?**

A: Absolutely not. Neo.Tax does not need to view source code and does not request it in the above permission set. We only need to see *pull requests,* the *repositories*, and the *person* doing the pull request.

**Q: How does this match to my cost data?**

A: To match to cost data, you’ll provide a mapping between Github user id and Employee work email.

**Q: Can I use both GitHub and JIRA with** **Neo.Tax****?**

A: Yes, you can integrate both systems, though we don't typically recommend this as a starting approach. The most effective use case for dual integration is when different teams within your organization use different systems exclusively—for example, if your development team works primarily in GitHub while your project management team relies on JIRA.

We recommend beginning with your most comprehensive or widely-used system first, then evaluating any coverage gaps before adding the second integration. This approach helps avoid unnecessary complexity and duplication while ensuring all teams have access to Neo.Tax functionality within their preferred workflow.

Your implementation team will work with you to determine the optimal integration strategy based on your specific team structure and usage patterns.