> For the complete documentation index, see [llms.txt](https://docs.flosum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flosum.com/devops/settings/git-integrations/connecting-a-github-repository.md).
# Connecting a GitHub Repository
##  Overview
This article shows you how to connect your GitHub repository to DevOps so that Salesforce metadata managed in DevOps branches syncs automatically with your GitHub repository. This ensures that your branches, commits, and pull requests are fully tracked in your Git-based version control system.
{% hint style="info" %}
#### GitHub Personal Access Tokens
DevOps connects to a GitHub repository using a Personal Access Token. You can use either a **Classic** token or a **Fine-Grained** token, depending on your company's requirements. The instructions below cover both methods, but you only need to create one type of token.
{% endhint %}
## GitHub Prerequisites
{% stepper %}
{% step %}
### Repository
The DevOps-to-GitHub integration syncs all branches, commits, and pull requests to a single GitHub repository. This repository can be public or private and can be owned by an organization or an individual user.
The screenshot below shows a private repository **flosum-devops-example** that is part of the **Flosum-Example** organization.
{% endstep %}
{% step %}
### Personal Access Token - Classic
{% hint style="info" %}
A **Classic** token applies to every repository your GitHub account can access and needs only two scopes. The following instructions explain how to create one.
{% endhint %}
1. Log in to your GitHub account.
2. Click your profile picture in the upper-right corner to open the dropdown menu.
3. Click **Settings**.
4. Access **Developer settings > Personal access tokens > Tokens (classic)**.
5. Click the **Generate new token** dropdown menu.
6. Click **Generate new token (classic)**.
7. Enter a description of the token in the **Note** textbox.
8. Click the **Expiration** dropdown and select the date when you want the token to expire.
9. Select the following **Scopes**:
1. **repo**
2. **workflow**
10. Click **Generate token** at the bottom of the page.
11. Copy the token and save it securely. You will need this token when connecting DevOps to your GitHub account.
{% endstep %}
{% step %}
### Personal Access Token - Fine-Grained
{% hint style="info" %}
A **Fine-Grained** token is limited to the repositories and permissions you select, so it gives DevOps narrower access than a **Classic** token. The following instructions explain how to create one.
{% endhint %}
1. Log in to your GitHub account.
2. Click your profile picture in the upper-right corner to open the dropdown menu.
3. Click **Settings**.
4. Access **Developer settings > Personal access tokens > Fine-grained tokens**.
5. Click **Generate new token**.
6. Enter a name for the token in the **Token name** textbox.
7. Click the **Resource owner** dropdown and select the user or organization that owns the repository this token is for.
8. Click the **Expiration** dropdown and select the date when you want the token to expire.
9. Under **Repository access**, select **Only select repositories** to limit the scope of this token to only the repositories you select.
{% hint style="info" %}
You can also select **All repositories**, but the token will then have access to any new repositories added to the **Resource owner**.
Do not select **Public repositories**. This option grants read-only access, and the DevOps GitHub integration requires read and write permissions.
{% endhint %}
10. Click the **Select repositories** dropdown and check all the repositories to include with this token.
11. Under **Permissions**, click **Add permissions** to add each of the permissions in the table below.
12. Set the **Access** dropdown for each permission to match the Access column in the table below.
| Permission | Access |
|---|
| Administration | Read and write |
| Contents | Read and write |
| Metadata | Read-only |
| Webhooks | Read and write |
{% hint style="info" %}
The **Metadata** permission is added automatically when another permission is added.
{% endhint %}
13. Click **Generate token**.
14. Review the token's settings in the confirmation dialog and click **Generate token**.
15. Copy the token and save it securely. You will need this token when connecting DevOps to your GitHub account.
{% endstep %}
{% endstepper %}
## Connect DevOps to GitHub
{% stepper %}
{% step %}
### Access Git Integration Settings
1. Click **Git integration** under the **Settings** section in the left sidebar menu.
2. Click the **Settings** tab.
{% endstep %}
{% step %}
### Connect GitHub
1. Click the **Service type** dropdown menu.
2. Select **GitHub**.
3. In the **Organization** textbox, enter the GitHub organization name that owns the repository you are connecting to. Leave blank if connecting to a repository owned by your GitHub user account.
{% hint style="info" %}
#### Repository Path
The GitHub repository path the integration tries to connect to depends on whether the **Organization** field has a value.
If the **Organization** field has a value, the repository path is:
* `github.com/{Organization}/{Repository name}`
If the **Organization** field is blank, the repository path is:
* `github.com/{Username}/{Repository name}`
{% endhint %}
4. In the **Username** textbox, enter the GitHub username you are connecting this integration with.
5. In the **Token** textbox, enter the GitHub Personal Access Token you created in the section above.
6. In the **Repository name** textbox, enter the name of the GitHub repository you are connecting to.
7. Click **Connect**.
8. If the Git integration connects to your GitHub repository successfully, a success message appears. The **GitHub** connection then lists the organization and shows its status as **Connected**.
{% hint style="warning" %}
If the Git integration connection fails, check the error message to determine the cause. Once fixed, try connecting again.
{% endhint %}
{% endstep %}
{% step %}
### GitHub Synchronization
Once connected, all DevOps branches will begin to sync with the GitHub repository. You can check the sync progress in the **Activities** tab.
{% endstep %}
{% step %}
### GitHub Repository
The screenshot below shows an example of a GitHub repository that is connected to and synced with DevOps.
{% endstep %}
{% endstepper %}
---
# 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://docs.flosum.com/devops/settings/git-integrations/connecting-a-github-repository.md?ask=&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.
