---
title: Authentication
description: Securely authenticate your workflows using personal access tokens (PATs).
---

Copilot requires a fine-grained personal access token to perform certain actions, such as creating branches, updating pull requests, or managing project boards.

<Info>Originally, the workflow also made use of the GITHUB_TOKEN for some basic tasks executed within the workflow's scope. However, to simplify the configuration and maintain a single unified bot, the use of this token has been removed, leaving only the necessary PAT.</Info>

<Warning>**When the event actor is the same as the token user**: If the user who triggers the workflow (e.g. the person who opened the issue or pushed the branch) is the same as the account that owns the PAT, the action **only runs single actions** (if one is requested) or **skips** the normal issue/PR/push pipelines. This avoids the bot reacting to its own actions. Use a dedicated bot account (different from the actor) if you want full pipeline behavior on every event.</Warning>

<Steps>
  <Step title="Who is the bot?">
    Choose which account will be used to create your PAT. This account will act as your bot.
    - For individual developers, it is recommended to use your own account as the bot.
    - In organizations and enterprise accounts, it is better to use a separate, dedicated account. For example, this project belongs to [**vypdev**](https://github.com/vypdev), and the selected bot account is [**vypbot**](https://github.com/vypbot).
  </Step>
  
  <Step title="Create the PAT">
    Once you’ve selected the account that will act as the bot:
    - Go to [**Settings**](https://github.com/settings/profile).
    - Navigate to [**Developer settings**](https://github.com/settings/apps).
    - Then go to **Personal access tokens**.
    - In the left sidebar, select [**Fine-grained tokens**](https://github.com/settings/personal-access-tokens).
    - Click the [**Generate new token**](https://github.com/settings/personal-access-tokens/new) button.
    
    Now you can start configuring your new token. Set a meaningful name and description to easily distinguish it from other tokens. This might seem redundant, but it helps reduce the risk of accidentally deleting the token.

    Pay close attention to the **Resource owner** field:
    - If your bot account does not belong to an organization (individual developer), you should keep your own account selected when creating the token (this is usually the default value, so you likely won’t need to change it).
    - If your account belongs to an organization, make sure to select the organization that this token will operate under. 

    In the **Repository access** section, you need to select the scope for which you want this token to operate. We recommend choosing **All repositories** to quickly configure Copilot on any repository the bot account has access to.

    Set these permissions for the repository:

    - **Actions**: Read and write
    - **Administration**: Read and write
    - **Commit statuses**: Read and write
    - **Contents**: Read and write
    - **Issues**: Read and write
    - **Metadata**: Read-only
    - **Pull requests**: Read and write
    - **Secrets**: Read-only
    - **Variables**: Read-only
    - **Webhooks**: Read and write
    - **Workflows**: Read and write

    **If your bot belongs to an organization** set these permissions for the organization:

    - **Custom repository roles**: Read-only
    - **Issue Types**: Read and write
    - **Members**: Read-only
    - **Projects**: Admin
    - **Secrets**: Read-only
    - **Self-hosted runners**: Read and write
    - **Variables**: Read-only

    Finally press the **Generate new token** button.

    <Warning>Make sure to **copy the generated PAT**, as it will not be visible again.</Warning>
  </Step>

  <Step title="Create the secret">
    It’s time to create a new Secret:

    If your bot account does **not** belong to an organization (individual developer):
    - Go to the repository where you want to implement Copilot.
    - Then, navigate to **Settings**.
    - In the left sidebar, click on **Secrets and variables**, then **Actions**.
    - Click **New repository secret**.
    - Define a name for the secret and paste the previously created PAT in the **Secret** field.
    - Finally, click **Add secret**.

    If your bot account **does** belong to an organization:
    - Go to the **Settings** of your organization.
    - In the left sidebar, click on **Secrets and variables**, then **Actions**.
    - Click **New organization secret**.
    - Define a name for the secret and paste the previously created PAT in the **Secret** field.
    - Select the **Repository access** level where you want this secret to be available. We recommend selecting **All repositories**.
    - Finally, click **Add secret**.
  </Step>
  <Step title="Consume the token">
    In each workflow that consumes Copilot, make sure to pass the PAT you just created with the `token` property:

    ```yml
    name: Copilot - Issue

    on:
      issues:
        types: [opened, reopened, edited, labeled, unlabeled, assigned, unassigned]

    jobs:
      git-board-issues:
        name: Git Board - Issue
        runs-on: ubuntu-latest
        steps:
          - uses: vypdev/copilot@v2
            with:
              project-ids: 1,2
              token: ${{ secrets.PAT }}
    ```
  </Step>
</Steps>