authentication.mdx

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

For a first installation, follow Set up with the web assistant, which introduces each credential at the point it is needed. This page is the permission and recovery reference.

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.

For guarded PR approval, this same runtime PAT submits the native review. It must have Pull requests write permission and must resolve to a different immutable GitHub user ID from the PR author. The local setup PAT never approves; unreadable branch rules or an unverifiable runtime identity keep the feature in non-approval mode.

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.

copilot setup --web offers the same guided or manual PAT choices in a local browser page. It has separate masked inputs for the temporary operator PAT and the bot PAT, displays the relevant grants next to each step, and verifies identity and access through the same setup use cases as the terminal. The browser never calls GitHub with a PAT directly or stores PAT values. GitHub's own tab handles account switching, 2FA, repository selection, and creation. The local page cannot prove that a browser extension or another process under your OS user cannot see the value while you paste it. Afterward, delete the temporary setup PAT in GitHub yourself; do not delete the bot PAT while the installed Actions Secret still depends on it.

The web assistant does not dispatch or temporarily install a credential-health workflow before you press Apply setup. Existing Secret values cannot be read back: re-enter the bot PAT to check its grants, and treat any preserved optional provider Secret marked unverifiable as unknown until a later copilot doctor/workflow check. The terminal setup retains its existing credential-health behavior.

Assisted creation in the terminal

When copilot setup needs a PAT interactively, it offers a guided link (the default) or manual entry. In guided mode it first asks the setup choices that determine PAT permissions: issue workflows, initial tag, Secret and Variable management and storage scope, PR approval mode, and Projects. Choices already fixed by flags or --config are not asked. You review the resulting grants before the link appears; these answers carry into the full wizard without being asked twice. The terminal first shows a short summary of required grants; choose view full permission table at review to inspect every grant, reason, and condition, then return to the same review without repeating setup choices. Choosing manual PAT entry shows the full table directly. The later bot PAT prompt has its own full-table option based on the finalized workflow grants, not on the temporary setup PAT. When Secret management is selected, the first link already prefills repository Actions: read and write, Contents: read and write, and Workflows: read and write for possible credential-health checks. These grants are conditional: authenticated inspection and the approved plan determine which write checks are needed. Disabling Secret management omits these health-write grants; approval-only CI inspection keeps Actions read. The link remains provisional for inherited organization resources and later changes to your choices. If the final plan needs additional grants, setup stops before applying it and prints a corrected link. Update the PAT in GitHub or create a replacement, then rerun setup. Guided setup shows the account returned by GitHub and asks you to confirm it.

In the web assistant, a blocked permission result keeps a Create corrected setup PAT link with the final required grants. The link uses final required grants, including any health-write grants that inspection confirms are needed. An older PAT created from a previous link may still lack Actions or Workflows write. Select the target repository in the updated GitHub form, create or correct the PAT, close the old local session and start copilot setup --web again. If temporary cleanup or a concurrent Secret collision needs inspection, resolve that first. An Actions check stopped by workflow preparation remains Unverifiable; it does not establish that the Actions grant is missing.

For Projects, this early choice is only whether you want the integration. Listing private organization Projects requires authorization, so the assistant cannot reliably ask you to select Project numbers before the setup PAT exists. If you opt in, the guided setup PAT requests organization Projects: read. The read-only check inspects at most two pages of up to 100 accessible organization Projects each. A non-public Project on either page confirms the read grant. If no non-public Project appears within that bound, including a public-only or empty response with more pages still available, discovery can continue but the PAT grant remains Read available; access to each selected Project is checked again later. After you enter that PAT, the assistant lists the accessible Projects and lets you choose their numeric Project numbers and, when available, their Status options. You can enter a Project URL or number manually if discovery is unavailable, and must verify that the bot account can access each chosen Project. The separate bot PAT needs Projects: read and write to add and update items when the workflows run. Its audit also checks viewerCanUpdate for every selected organization Project: creating a disposable Project alone does not prove the account’s role on an existing one. Fine-grained PATs cannot use the same personal-Projects listing endpoint as organization Projects; personal-owner setups use the documented manual path rather than pretending to discover them.

If you choose Review all setup choices again at the permission preview, the terminal clearly marks a second pass over your saved answers. Press Enter to keep an answer, or change it; afterward you return to the same PAT review with permissions recalculated. No PAT link has been accepted and no setup mutation has started merely because you revisited these choices.

After the plan, the bot link uses the selected workflow permissions. Enter the expected bot login first: setup resolves its GitHub numeric ID, then checks the PAT's own /user identity against that ID before any Secret write. A manual or non-interactive PAT retains the existing permission audit but does not gain this extra identity binding. A wrong bot account blocks installation.

The guided bot link names the selected account, for example Create bot PAT as @vypbot, with an adjacent warning to use that GitHub account. A private browser window can help when your regular window uses the operator account; sign in as the bot and check GitHub's active account before generating the PAT. If the submitted PAT belongs to another account, setup shows both identities and offers Enter another bot PAT or Stop setup. Re-entry is explicit: it keeps your answers, approved plan and selected bot in the same session, clears the rejected input, and verifies the new PAT's numeric identity and permissions before continuing. Delete the unused wrong-account PAT in GitHub. Closing the session still ends the run; progress is not saved across restarts.

In current-repository Customize configuration, the bot Secret PAT is supplied and validated, even when you preserve other existing Secrets. It uses the scope you selected (or its explicit override). The plan and hidden input warn when that destination already contains PAT; it is replaced only after the new value passes identity, target repository access and required permission checks and setup is approved. Replacing an organization PAT can affect other repositories using it: validation for this repository does not certify their requirements. Setup checks organization namespace metadata even when the existing PAT is not yet shared with this repo. It cannot recover, copy or move the previous Secret value.

If organization PAT storage is selected but repository Secret PAT exists, setup pauses because GitHub will prefer the repository value. Open repository Actions Secrets in GitHub, delete that repository Secret manually and select I have deleted the repository PAT — check again. Copilot queries GitHub again; clicking the button alone does not clear the conflict. A still-present Secret or failed read keeps your answers and recovery choices. Alternatively, Store PAT in the repository instead changes only the PAT override and rebuilds the plan for approval. Stop setup ends the run. Copilot never deletes a Secret during this flow; a Secret you delete in GitHub is not restored if you stop.

Both links use GitHub's documented fine-grained PAT form. When PR assessment is selected in recommend or guarded mode, the bot link prefills repository Variables: Read (actions_variables=read). If the effective PR_APPROVAL_POLICY is stored at organization scope, it also prefills organization Variables: Read (organization_actions_variables=read). An existing repository policy takes precedence over an inherited organization policy. With assessment off, the bot does not request these grants. Setup uses its separate operator PAT for provisioning Variables; the bot's read grant does not give it Variables write access. If you enable assessment after creating the bot PAT, update these permissions in GitHub and complete any organization approval before rerunning the observer. They do not sign you in, complete 2FA, generate or revoke a token, or choose an individual repository. Check the active browser account, change All repositories to Only select repositories, select only the target repository, and review the final GitHub form. A guided setup PAT uses a one-day suggested expiry; delete it yourself in GitHub PAT Settings afterward. The bot PAT uses a 90-day suggested expiry, may be shortened by organization policy, and remains in Actions Secret PAT; arrange renewal before it expires. GitHub's documentation is inconsistent: its PAT limitations list calls out the Checks API, while the check-runs endpoint reference lists fine-grained PATs with Checks: read. The published PAT URL-permission table does not list checks, although the form may currently accept checks=read. Recommendation-only setup does not require Checks access on the temporary operator PAT. If check discovery is unavailable, enter the exact CI check, source App ID and workflow manually; producer evidence remains unverified until independently attested. This permits a fine-grained setup PAT without claiming native approval readiness. Guarded setup and the runtime bot in both active modes still require Checks access. Use a compatible credential for those roles if GitHub does not offer the permission; do not keep recreating fine-grained PATs to request an unavailable grant. The guided links include Checks when required, but the final API audit determines access. Setup never assumes that a prefilled URL proves API access. Existing command-line token flags also remain, but putting a PAT in a command can expose it in shell history or process listings.

Permission tables in copilot setup

Immediately before each hidden PAT prompt, interactive setup prints a least-privilege table with the GitHub permission, repository or organization scope, access level, purpose, and any enabling condition. After a newly supplied or re-entered token is entered, setup prints the same ordered matrix with one of these states:

Status	Meaning	Setup behavior
✅ Verified	An authentication-bound read or completed temporary write transaction proved the requested capability.	Continue.
Read available	An exact public read succeeded without independently proving the PAT grant.	Use that read; protected operations and writes are checked separately.
❌ Missing	GitHub deterministically rejected a required capability after identity and repository access were established.	Stop before the dependent mutation and name the permission to grant.
? Unverifiable	A read did not prove the PAT grant, or its response was ambiguous/transient.	Required reads block unless an exact successful public-repository read or organization Projects list has separate operational evidence. Required writes must pass a temporary create/read/delete test during initial PAT verification.

A 403 is not automatically a missing-permission result. Copilot reports it as Missing only when bounded GitHub metadata explicitly identifies a permission denial and there is no rate-limit, retry, or SSO signal. Bare responses, the generic provider message Forbidden, rate-limited responses, SSO-constrained responses, and otherwise ambiguous 403 responses remain Unverifiable; raw provider messages are never printed. Malformed response bodies or unreadable provider headers are handled the same way.

A successful 200 is not automatically permission evidence. Repository metadata, commits, labels, workflows, checks, pull requests, and workflow files may be anonymously readable on a public repository. Copilot marks those reads Verified only when the same bounded probe establishes that the repository is private; on a public repository, or when visibility is unknown, setup cannot claim the grant: public success is Read available, while unknown visibility remains Unverifiable. Administration uses the protected Actions-permissions endpoint, which requires Administration read; listing rulesets alone cannot prove that grant. Secret and Variable inventory reads are permission-bound; their corresponding write grants wait for temporary create/read/delete tests during initial PAT verification. Public organization Issue Types reads remain Unverifiable as PAT evidence. After valid token identity, a successful public repository read can be used for that exact operation while its row says Read available. An organization Projects list containing only public Projects, or no Projects, is similarly usable for discovery without proving the PAT grant. A malformed or denied Projects response is not usable. After the approved plan selects Projects, setup reads each Project by its exact organization and number. Every selected read must succeed; a private Project response proves the scoped read, while successful public Project responses remain operationally usable without claiming the PAT grant was independently established. The public organization members list can omit concealed members, so it cannot establish Members-read capability. Copilot instead checks the authenticated user's active organization membership through GitHub's permission-bound Members-read endpoint; only a valid response for the selected organization marks that row Verified. This positive operational fact is not granted to a failed, ambiguous, or visibility-unknown probe, organization Issue Types, or any write.

The distinction between an available public read and a verified grant is intentional. GitHub's X-Accepted-GitHub-Permissions response header describes what an endpoint requires; it does not enumerate every effective grant of the presented fine-grained PAT. Each required Write capability is tested with a disposable resource and requires confirmed cleanup.

At PAT entry, the assistant checks identity and required reads, confirms the guided operator account, then tests required Writes with isolated temporary resources. Guided mode defers the prefilled conditional health Writes until authenticated inspection and plan approval establish they are required. Manual and supplied-token paths also test their displayed conditional Writes. PAT-entry and environment selection explain these tests before they start. --dry-run performs reads only, including leaving pending recovery records untouched. Installation still needs plan approval. A public read can be usable without independently proving the PAT grant; the UI labels it accordingly. Failed required reads or writes stop setup, and operator confirmation cannot promote an unknown row to verified.

ready is true only when every required read succeeded or is positively usable and every required write completed its own temporary create/read/delete cycle. --yes approves the plan; it is not permission evidence. The old --confirm-unverifiable-write-permissions option is rejected. Issues Write is tested by creating and reading an exact temporary Issue, then deleting it by its GitHub node ID and confirming absence. GitHub can deny Issue deletion even when the PAT has Issues Write. If so, setup closes the exact Issue, reports its number, retains the cleanup record and blocks further setup until deletion is confirmed. This test can leave notifications and audit history. Actions and Pull request tests may also leave GitHub history and notifications after cleanup; the PAT-entry guidance discloses these tests before they start.

Copilot reserves copilot-permission-test-* for disposable permission branches (currently a 32-character random hexadecimal suffix). Current Commit and Branch Sync workflows exclude those refs before starting a job. Existing installations need their workflow update reviewed and merged before that protection applies; updating the CLI alone cannot change the workflows that run during the first permission check. User-owned CI and pull-request workflows can still run and leave notifications or audit history. Setup preserves their configuration. For a bot Actions Write check, the already verified setup PAT prepares and cleans the isolated branch and disabled-job workflow. Only the bot PAT dispatches and reads its exact run. The bot link therefore does not need Workflows Write just to validate Actions. Setup displays its own Contents, Actions and Workflows Write prerequisites when bot release/hotfix dispatch is selected and Secret management is enabled. A denied bot dispatch or readback still blocks setup; the setup PAT cannot substitute for it.

If Actions Write is Unverifiable because the temporary workflow could not be written, the dispatch was never tested. Check repository Contents → Read and write and repository Workflows → Read and write on the setup PAT, as well as repository selection and organization authorization. Workflows is a separate grant: granting Actions write alone does not grant it. A separate Workflows Write: Missing result means GitHub explicitly denied that workflow write; do not treat a denied request as verified access. If there is no eligible workflow_dispatch workflow on the default branch, install one before retrying. The web result explains the prerequisite without displaying raw GitHub errors. After correcting the PAT, start a fresh setup run. These rules apply separately to each audited role; the web result names the bot PAT when its audit failed.

GitHub can return node: null together with a node-scoped NOT_FOUND error after deleting a temporary Project. Copilot confirms absence with a complete, authorized organization lookup for its private random title before clearing the recovery record. Permission errors, an incomplete lookup or a remaining exact title still block cleanup. An older false pending-cleanup record is rechecked automatically before the next audit; stop the old local session first.

If a temporary permission resource cannot be confirmed as deleted, the row shows pending cleanup and setup stops. Cancelling or losing the local session during that failed cleanup is reported as partial; the local recovery journal is checked before another permission audit. A cancelled audit whose temporary resources were all confirmed deleted remains cancelled.

The setup-PAT table is comprehensive because it appears before the interactive feature choices are final. Repository Metadata and the read capabilities needed for initial inspection are required; later write and organization permissions state the feature/storage condition that makes them applicable. The workflow-PAT table is calculated from the final setup configuration, so guarded approval, release/hotfix, organization issue types, Projects, and organization Variables appear only when selected. That calculation uses the effective remote scope, including a preserved organization-level PR_APPROVAL_POLICY; leaving an existing organization Variable in place therefore still requires organization Variables read access for the workflow PAT.

The repository Contents read check uses the read-only commit-list endpoint. A documented empty-repository response is accepted as proof only after repository metadata proves the repository is private. For a public repository that same response remains Read available without PAT-grant evidence; Contents write still needs its temporary branch create/read/delete test. An ambiguous 404 is never treated as empty-repository evidence.

GitHub Action registers the resolved workflow PAT for log masking, including values supplied through INPUT_VARS_JSON; a required empty JSON value fails before execution. Git credentials are scoped to https://github.com/ in the child process environment, and are not written to repository URLs or Git config.

Permission checks use at most four concurrent GitHub probes. At PAT entry, identity and required reads run first; after guided account confirmation, required Write grants are tested with a temporary resource that is read back and cleaned up. Guided health prerequisites wait until the approved plan requires them; manual and supplied-token paths also test conditional rows. Plan approval remains required for installation; dry-run performs no writes or recovery. Disposable branches are deleted only after their exact ref and journaled commit match. Actions run cleanup also matches the journaled workflow ID, run ID, branch and event.

An Actions run can remain queued briefly even when its only job is skipped. Copilot waits with bounded backoff for about a minute, in addition to individual request deadlines, before reporting unresolved run cleanup. It deletes only a completed run and then confirms absence before removing the recorded branch. If this wait expires, close the failed local session and retry with the required setup PAT; the next audit first recovers that exact run and branch from the local journal. A timeout does not establish that the Actions grant is missing.

An older dispatched record without the workflow identity stops recovery before requests and gives a manual cleanup path. Verify the exact dispatch run and recorded branch commit, confirm their cleanup, then remove only its matching journal file and retry; see troubleshooting. A branch advanced by another actor, or a legacy journal without its commit, requires manual inspection; GitHub has no atomic compare-and-delete ref endpoint. Two audits for the same repository cannot recover each other’s active resources. Secret writes use GitHub's create-or-update endpoint: Copilot chooses a private 256-bit random name, confirms absence first, and requires the create response. GitHub does not offer atomic create-only Secret writes. If it reports an update, setup stops, does not delete the Secret, and retains an incident marker in ~/.copilot/setup-permission-probes/. Inspect the GitHub audit trail because a concurrent value may have been replaced; reconcile it before manually removing that marker. A retry cannot automatically delete the unknown Secret. Results remain in the displayed requirement order even when provider responses complete out of order, reducing secondary-rate-limit pressure without making the report nondeterministic.

If a conditional repository or organization Secret or Variable inventory read is unavailable before feature selection, setup keeps that access state distinct from an empty inventory and continues planning. When the approved plan actually needs that resource at either scope, or must inspect both scopes to preserve an unoverridden existing value, the final setup-PAT table promotes it to required and stops before any dependent write until the named permission is corrected. If GitHub can only report the permission as unverifiable and the required inventory remains unavailable, setup still fails closed after the final table and before credential choices or resource targeting; it never treats the missing inventory as an empty list. Repository inventory is required even when every selected resource is explicitly organization-scoped or uses an organization default with preserveExisting: false: a same-name repository resource takes precedence at runtime. If the repository inventory is unavailable, or it reveals a same-name shadow, setup blocks before provisioning the organization target. Choose repository scope or remove the shadow after inspecting it. If required repository or organization inventory is unavailable, the wizard recognizes that blocked result immediately after running the final setup-PAT permission audit. The CLI reports the storage validation error with a failing exit code without starting a second audit or inventory validator. It does not continue into plan confirmation, credential collection, workflow comparison, target resolution, or mutation. The provisioning workflow repeats this fail-closed rule after approval: if it cannot obtain an authoritative remote snapshot or required selected inventory access, it stops before Secrets, Variables, labels, issue types, and tag writes with bounded recovery guidance, including for a repository-scope default. When an organization Secret or Variable has selected visibility, setup must confirm this repository has access before counting it as configured. It preserves existing visibility. New Variables include repository access when created; existing Variables reuse access confirmed by GitHub's inherited inventory. Otherwise setup grants access separately. Missing required capabilities prevent the value write, and a rejected required grant prevents a success result. An API failure after a value write may require inspecting that resource before retrying.

GitHub does not reveal Secret values through its API. In Customize, Copilot validates new credentials with provider metadata requests and may validate existing remote Secrets by dispatching the installed copilot_credential_health.yml workflow. Setup proves the exact file on the selected main ref and dispatches that path only when the workflow is also registered or installed on GitHub's default branch. Plain copilot doctor may create an Actions run; copilot doctor --read-only never dispatches it and leaves Secret values unverified. The health workflow reports each requested credential independently, but that bounded reachability result is not a permission audit. In Customize, if PAT already exists, interactive setup asks you to re-enter it and runs the complete workflow-PAT permission matrix before provisioning; unattended setup must supply PAT again or stops before mutation. 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.

Terminal setup may attempt a temporary credential-health workflow creation before final Apply when checking existing Secrets. That request can create Git commits even if the workflow is later removed. If setup stops after this attempt, it reports a partial outcome: inspect the selected branch and GitHub workflow history before retrying. An ambiguous create failure is treated conservatively as a possible remote change. The browser setup path does not perform this pre-Apply bootstrap.

The final setup-PAT audit requires GitHub to verify whether the repository owner is a person or an organization. If that remote owner type is unknown or unavailable, setup stops before provisioning and asks you to retry inspection; the owner type you selected earlier for a guided link is only provisional. Potential organization grants remain visible in the permission preview.

For other existing credentials, choosing keep works only when the selected storage policy preserves the Secret in its current repository or organization scope. With preserveExisting: false, or an override that moves the Secret, setup requests and validates the value again before provisioning the new target.

An Actions API 404 does not by itself mark the credential-health workflow as missing. Setup first proves repository Contents visibility, then reads the exact workflow path. Only a subsequent exact-path 404 is confirmed absence; every unreadable or ambiguous state remains unavailable and never authorizes temporary workflow creation. The initial check may use the default branch; after the questionnaire chooses the main branch, setup repeats both Contents reads on that selected ref before its final PAT audit. A failed selected-ref lookup cannot inherit the default-branch result. The setup-only bootstrap adapter independently repeats the selected-ref reads before dispatch or any write, even if Actions finds a workflow on the default branch. If the final PAT audit denies required access, setup reports a bounded blocked result with the selected configuration before storage validation or mutation. An exact-file response counts as installed only when it identifies a file with a non-empty sha; an empty object or directory-like response is unavailable. Once installed state is proven on the selected ref, setup dispatches that path and ref only if GitHub's Actions index resolves the workflow or, after an index 404, exact Contents inspection also proves it installed on the default branch. A selected-ref-only file cannot be dispatched. Missing state follows the bounded temporary-bootstrap flow only when a default-branch definition is available, or when setup can install the temporary file on the default branch itself. Temporary creation is create-only; setup records the created file SHA and removes it only if the selected-ref file still has that same SHA. A concurrent change is left intact with bounded cleanup guidance. Unavailable state never dispatches or mutates.

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.

For comment-driven assistance, read-only commands are available to anyone who can comment unless ai-members-only is enabled; with that policy, every requested agent task requires an authorized member, including generation of bounded dynamic product copy for a configured locale. Membership is checked only after live admission returns execute; no-op, blocked, and continuation-only outcomes do not query it. A locale-only catalog planner uses this membership check and does not require repository write permission. Non-AI status/help metadata remains available. File-modifying commands use a separate repository-write check: for both organization and personal repositories, the repository owner or a collaborator with push, maintain, or admin permission may request changes. Organization membership alone is not mutation authority. The workflow PAT still needs the relevant contents: write permission, and issue comments need an open PR to provide a branch for the change.

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). Initial version setup is automatic: enabled release/hotfix issues need a version baseline. Copilot checks remote `x.y.z`/`vx.y.z` tags with the setup PAT, preserves existing versions and creates `v1.0.0` only when none exist. Other issue workflows skip this step. Neither terminal nor web setup asks about it; `createInitialTag` is not a config-file option. Local moving Action tags (`v1`, `v2`, `v3`) are untouched, and a failed tag read stops creation.

When updating existing organization Variables, Copilot preserves their visibility and reuses confirmed repository access. It grants selected repository access separately only when needed. A failed Variable write names the resource and phase with a bounded reason. Review partial results before retrying; values and raw GitHub response bodies are never displayed.

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 Contents read for inspecting repository files and installed workflows; 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. Setup uses organization Projects **read**, not write, to list Projects after the PAT is entered. There is no separate Workflows read permission for inspection. 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. For existing Secrets, dispatching an installed `copilot_credential_health.yml` requires Actions write. Its isolated Actions permission test also requires Contents write for a disposable branch. If the exact trusted packaged workflow cannot be used, the test requires Workflows write for a verified no-job override; this prerequisite does not establish a Workflows grant automatically. Temporary installation on the setup branch is authorized only when the workflow is independently confirmed missing; unavailable or unknown workflow state never authorizes temporary creation. Contents write can also be required for an initial tag or another explicitly selected repository mutation.

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.

Read the required-permissions table before creating the token, then review
the permission-check table after entry. A `❌ Missing` required row must be
corrected before setup can continue. An ambiguous required
`? Unverifiable` read blocks unless a successful public-repository read or
organization Projects list has separate operational evidence. A required
write row must pass its own temporary
create/read/cleanup transaction; an assertion about the PAT settings cannot
make it pass.

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.

The default installation enables issue, PR, comment, commit, release, and
hotfix automation and therefore needs the write grants below. If you
disable capabilities in setup, follow the final workflow-PAT terminal table
instead: Metadata read is the only unconditional grant. For example, a
repository using only PR review needs Pull requests write, Contents read
for repository/commit inspection, and Actions read for the previous-run
queue check; release/hotfix dispatch upgrades Actions to write, and
file-editing routes or managed branches add Contents write. An issue
workflow that remains selected while the issue route is disabled does not
grant runtime authority.

For the default installation, set these permissions for the repository:

- **Actions**: Read-only for the previous-run queue check when any runtime route is enabled; read and write for release/hotfix dispatch
- **Administration**: Read-only when release/hotfix orchestration or PR approval assessment (`recommend` or `guarded`) is enabled, so runtime can inspect classic branch protection alongside effective rulesets.
- **Checks**: Read-only when PR approval assessment (`recommend` or `guarded`) is enabled, to verify current-head check runs and their producer App IDs. For ordinary pull-request automation, Checks is not required on the PAT: the supplied workflow grants job-local `checks: write` to its short-lived `GITHUB_TOKEN` for its own Check Run.
- **Contents**: Read for enabled runtime routes; read and write for managed issue branches, file-editing comment routes, or release/hotfix operations
- **Issues**: Read and write for issue automation, issue comments, commit-driven issue progress, inactive issue closure, or release/hotfix lifecycle
- **Metadata**: Read-only
- **Pull requests**: Read and write for PR automation/comments, commit-driven Bugbot review, issue-comment autofix, PR approval assessment cards (`recommend` or `guarded`), or release/hotfix promotion; native approval remains limited to `guarded` mode
- **Variables**: Read-only when PR approval assessment is enabled in `recommend` or `guarded` mode, to load `PR_APPROVAL_POLICY`. If setup creates, selects, or preserves an organization-level Variable, grant the corresponding organization Variables read permission as well.

Workflow installation and Secret/Variable administration belong to the separate setup PAT. The runtime matrix does not request Administration write, Secrets, Variables write, Webhooks, or Workflows. Some disposable audit operations need extra prerequisites: opening a draft PR needs a temporary changed branch (Contents write), the setup PAT needs Workflows write to prepare an Actions override, deleting a temporary Issue needs repository administration/organization enablement, and creating or deleting an organization Project may require a stronger organization role than updating an existing item. A runtime grant alone cannot satisfy these prerequisites. Inspect the failed phase; setup blocks rather than treating an incomplete transaction as verified or silently adding broad permissions.

**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 only when a capability performs a membership lookup: automatic issue/PR assignees, automatic PR reviewers, release/hotfix issue authorization, or `ai-members-only` on an enabled issue, pull-request, commit, or comment route or on an independently available agent-backed single action. Enabling ordinary issue/PR comment automation alone does not require this grant. Setup also omits it when assignment/reviewer counts are zero and no other membership-consuming route is active.
- **Projects**: Read and write only for the selected organization projects

The runtime PAT does not need organization Secrets, Variables write, Custom repository roles, or Self-hosted runners administration. Organization Variables read is needed only when the approval policy is supplied at organization scope.

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.

When setup requests this PAT, use its feature-derived terminal table as the
authoritative checklist for the selected installation. Review every result
row before allowing setup to store the token as the `PAT` Secret.

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

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**.

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 }}
```

Organization reuse and batch permissions

Reuse keeps existing Secret bindings, including PAT, without asking for their values or dispatching a health workflow. It reads only available trusted health evidence from the exact packaged workflow on the authenticated default-branch SHA, at most five minutes old. Missing/stale evidence means verification pending; a failed trusted check blocks that binding. Authentication does not prove the bot's full repository, Projects or approval capabilities.

The operator PAT needs readable repository and organization Actions resource metadata. Batch also needs Contents, Workflows and Pull requests Write to open setup PRs, plus the target's required label/issue-type grants. Organization Variables or Secrets Write is required only for explicitly reviewed additive selected-repository grants. No reused Secret or shared Variable value is written. The final review lists the exact temporary Write probes; a failed cleanup stops all installation work. Organization or runner-group policies are never weakened.

Select repositories explicitly in the PAT settings. The creation link is a permission aid; it cannot prove the selected repositories or organization approval. A limited discovery view is not an organization inventory guarantee. See the guided batch journey.