How to Set Up DocuCodes

This post walks you through setting up your DocuCodes account by authorizing it to access your GitHub content.

GitHub Authentication

Depending on your plan, DocuCodes offers two methods of authenticating with GitHub.

1. Personal plans - Personal Access Tokens
2. Team plans - DocuCodes GitHub App

Personal Plan - Personal Access Tokens

Personal Access Tokens are associated with your individual GitHub user account and, by extension, your individual DocuCodes user account. Only DocuCodes Personal Plans support authentication using GitHub Personal Access Tokens.

GitHub offers two types of personal access tokens: "Classic" and "Fine-Grained". Learn more in the official GitHub documentation. DocuCodes recommends using a Classic Token because they are easier to generate and provide more seamless access across multiple organizations. Fine-grained tokens require you to choose a single account or organization to access, meaning they are inherently limited to a single account or organization.

Classic Tokens

You can use the link below to create a Classic personal access token.

Create a Classic GitHub Token with the required scopes

To manually create a classic token:

1. Access classic tokens by going to "Settings" -> "Developer settings" -> "Personal Access Tokens" -> "Tokens (classic)"
2. Click "Generate" -> "Generate new token (classic)"
3. Enter a note (optional). This is for your own reference in GitHub.
4. Enter an expiration date. Set the expiration date to whatever you choose. PLEASE NOTE: DocuCodes does not keep track of this expiration date. You must update your PAT if it expires. To avoid this, you can set the expiration to "No expiration" or to a date far in the future.
5. Select scopes. Your PAT needs the following permissions:
   1. repo
6. Click "Generate Token"
7. Your token will be displayed. Copy your token and add it to DocuCodes (see below)

Fine-Grained

1. Access fine-grained tokens by going to "Settings" -> "Developer settings" -> "Personal Access Tokens" -> "Fine-grained tokens"
2. Give your token a name and (optional) description. These are just for your own convenience within GitHub.
3. Resource owner - This will determine whether your PAT can access repositories in organizations you have access to.
4. Expiration - Set the expiration date to whatever you choose. Fine-grained tokens currently have a maximum age of one year. PLEASE NOTE: GitHub requires an expiration date for fine-grained tokens (maximum 1 year). DocuCodes does not keep track of this date, so you will need to manually rotate your token before it expires to avoid service interruption. To avoid this, use a "Classic" token instead.
5. Repository access - Choose which repositories you want to access.
6. Permissions - Your PAT needs the following permissions:
   1. Contents - read only permission
7. Click "Generate Token"
8. Your token will be displayed. Copy your token and add it to DocuCodes (see below)

Adding the Token to DocuCodes

Once you have your access token, copy it and head back to DocuCodes.

1. Navigate to Settings in DocuCodes
2. Paste your PAT into the box labeled "GitHub Personal Access Token"
3. Click "Save Token"

Once you save your token in DocuCodes you will be unable to edit it. In order to update your token you will need to delete the existing token and add a new one.

Team Plan - GitHub App

DocuCodes Team plans enable you to integrate with GitHub using the official DocuCodes GitHub app. This allows greater security and access control.

Note: Only admins can install GitHub apps within DocuCodes.

Install the DocuCodes GitHub App

1. Navigate to Settings in DocuCodes
2. Confirm you see "Not Installed" under "GitHub App Install Status"
3. Click "Install App on GitHub"
4. Choose the installation target (this applies if you belong to multiple organizations or have a personal account and an organization account).
5. Choose whether DocuCodes should be able to access "All repositories" or "Only select repositories"
6. Click "Install & Authorize"
7. You will be redirected to DocuCodes. Confirm the "GitHub App Install Status" now shows "Installed"