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

Copilot uses two deliberately separate credentials:

- **Setup PAT (operator token):** entered in `copilot setup` or `copilot doctor`, used only for that local command, and never stored in the repository or in a GitHub Secret. The wizard validates it before making changes.
- **Workflow PAT (bot token):** owned by the bot account, stored as the repository or organization Secret `PAT`, and consumed by GitHub Actions at runtime. This is the token that gives the workflows their bot identity.

The setup PAT and workflow PAT may have different owners and permissions. Do not paste the workflow PAT into the setup prompt unless you intentionally want the same token to perform both roles.

<Info>GitHub does not reveal Secret values through its API. Copilot validates new credentials with provider metadata requests and validates existing remote Secrets through the read-only `copilot_credential_health.yml` workflow when it is installed on the repository's default branch. The health workflow reports each requested credential independently. Doctor can query and dispatch that installed workflow but has no bootstrap or repository-mutation authority; temporary workflow bootstrap is available only during setup. A preauthenticated Codex session is runner state, not a Secret: it is accepted only when the runtime preflight can execute `codex login status` successfully.</Info>

<Warning>**When the event actor is the same as the token user**: The action detects this before entering the workflow queue. It completes successfully without waiting or running the normal issue/PR/push pipeline. A valid explicit single action still runs. 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>

For comment-driven assistance, read-only commands are available to anyone who can comment unless `ai-members-only` is enabled; with that policy, every AI invocation requires an authorized member while non-AI status/help metadata remains available. File-modifying commands are always restricted to organization members in organization repositories. In personal repositories, the repository owner or a collaborator with `push`, `maintain`, or `admin` permission may request changes. The workflow PAT still needs the relevant `contents: write` permission, and issue comments need an open PR to provide a branch for the change.

<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 setup PAT">
    The person running setup needs a separate fine-grained PAT. Give it only the permissions required by the selected setup features: repository Metadata read and repository Contents/Workflows read for inspection; Administration read when release/hotfix setup or doctor must inspect classic branch protection; Issues write for labels; Variables write for Repository Variables; Secrets read/write when provisioning Secrets; Actions read/write when checking or dispatching credential health; and organization Issue Types or Projects permissions only when those integrations are selected. If setup will use organization-level Actions Secrets or Variables, the token also needs the corresponding organization Actions Secrets/Variables read and write permissions. Organization scope is valid only for repositories owned by an organization; setup detects personal repositories and stops before attempting organization writes. Contents write and Workflows write are required only if the operator chooses to modify workflow files through the GitHub API.

    Enter it in the hidden prompt, or use `--token`/`PERSONAL_ACCESS_TOKEN` for automation. It remains in memory for the command and is not written to `.env`, a config file, or the `PAT` Secret.
  </Step>
  
  <Step title="Create the workflow 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, select only the repositories that will run Copilot. Avoid **All repositories** unless a separately reviewed organization policy genuinely requires it.

    Set these permissions for the repository:

    - **Actions**: Read and write
    - **Administration**: Read-only when release or hotfix orchestration is enabled, so runtime can combine classic branch protection with effective rulesets before an automatic merge or enqueue
    - **Checks**: Not required on the PAT when using the supplied pull-request
      workflow. That workflow grants job-local `checks: write` to its short-lived
      `GITHUB_TOKEN` and passes it only as `COPILOT_EVIDENCE_TOKEN`. Grant Checks
      read/write to the PAT only for a reviewed custom workflow that deliberately
      uses the PAT as the Check Run fallback.
    - **Contents**: Read and write
    - **Issues**: Read and write
    - **Metadata**: Read-only
    - **Pull requests**: Read and write

    Do not grant Administration write, Secrets, Variables, Webhooks, or Workflows permissions to the runtime PAT unless an independently reviewed extension actually uses them. Workflow installation and Secret/Variable administration belong to the separate setup PAT.

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

    - **Issue Types**: Read and write only when issue-type automation is enabled
    - **Members**: Read-only
    - **Projects**: Read and write only for the selected organization projects

    The runtime PAT does not need organization Secrets, Variables, Custom repository roles, or Self-hosted runners administration.

    Release and hotfix promotion/reconciliation PRs must still use this PAT (or
    an explicitly designed GitHub App token), rather than `GITHUB_TOKEN`, because
    most events produced by `GITHUB_TOKEN` do not start another workflow run.
    That is what allows the marked PR `closed` event to wake
    `copilot_deployment_orchestration.yml`.

    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 PAT Secret">
    It’s time to create the `PAT` Secret used by the workflows. The interactive setup can validate and create/update it directly when the setup PAT has Secrets write permission. Otherwise create it manually:

    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 the name as `PAT` and paste the workflow 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 only the repositories that run Copilot. Avoid **All repositories** unless a separately reviewed organization policy requires it.
    - 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@v3
            with:
              project-ids: 1,2
              token: ${{ secrets.PAT }}
    ```
  </Step>
</Steps>