# GitHub Configuration

## Creating an Access Token in GitHub

**Supported GitHub Authentication**

You can use either classic personal access tokens or fine-grained personal access tokens. For more information on the differences between these token types, refer to the [GitHub Docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).

Basic authentication (username and password) is not supported. This method is less secure and [GitHub has deprecated its use](https://github.blog/security/application-security/token-authentication-requirements-for-git-operations/) for authenticating Git operations since August 13, 2021.

### Required Permissions for Tokens (classic)

| Feature | Required GitHub Scope(s) |
| --- | --- |
| [Automated Commit Feedback](https://help.sonatype.com/en/automated-commit-feedback.html "Automated Commit Feedback") | `repo:status` |
| [Automated Pull Requests](https://help.sonatype.com/en/automated-pull-requests.html "Automated remediation") | `repo` |
| [Pull Request Commenting](https://help.sonatype.com/en/pull-request-commenting.html "Pull Request Commenting") | `repo` |
| [Pull Request Line Commenting](https://help.sonatype.com/en/pull-request-commenting.html "Pull Request Commenting") | `repo` |
| [Automatic Role Assignment](https://help.sonatype.com/en/source-control-rest-api.html#automatic-role-assignment) | `user:email`, `read:user` |

See [this explanation for details of GitHub scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps).

The items above are classic PAT scopes (coarse-grained). Fine-grained PATs use permissions instead (for example `pull_requests=write`).

### Required Permissions for Fine-Grained Tokens

Fine-grained personal access tokens (PATs) are configured with:

- **Repository access**: All repositories or only select repositories (a subset).
- **Repository permissions**: What the token can do in those repos (see [table below](https://help.sonatype.com/en/github-configuration.html#repository-permissions "Repository Permissions").

[GitHub’s REST API](https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api) surfaces the technical permission strings for fine-grained permissions via the `X-Accepted-GitHub-Permissions` response header (examples include `pull_requests=write` and `contents=read`). The permission-string mappings below match [GitHub’s published list for fine-grained PAT permissions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#repository-permissions).

#### Repository Permissions

| Repository Permissions | Access Levels | Permission String |
| --- | --- | --- |
| Administration | Read-only | `administration=read` |
| Commit statuses | Read and write | `statuses=write` |
| Contents | Read and write | `contents=write` |
| Deployments | Read-only | `deployments=read` |
| Metadata | Read-only | `metadata=read` |
| Pull requests | Read and write | `pull_requests=write` |

### How to Create the Access Token

1. Log in to GitHub.
2. In the upper-right corner, click your avatar and select _Settings_.
3. In the left menu, click _Developer Settings_.
4. In the left menu, select _Fine-grained tokens_ or _Tokens (classic)_.
5. Click the _Generate new token_ button.
6. Select _Generate new token_ for fine-grained, repo-scoped tokens, or _Generate new token (classic)_ for general use.
7. Save your PAT. You will not be able to view this token again.

## Protecting the Target Branch in GitHub

You can prevent users from merging Pull Requests with failing IQ Policy Evaluations with a Branch Protection Rule. IQ Policy Evaluations must be set to Fail at the Source Stage.

To protect a branch:

1. Select a Repository.
2. Click _Settings_.
3. Select Branches from the sidebar.
4. Click _Add rule_ or edit an existing rule.
5. Check to _Require status checks to pass before merging._
6. Check _IQ Policy Evaluation_.
7. Save Changes

|     |
| --- |
|  |

**Note**
The **IQ Policy Evaluation** status check will not appear in the list of status checks found in the last week for this repository until the first policy evaluation status has been added to the repository.

|     |
| --- |
|  |