Skip to content

Commit 3bb0e43

Browse files
jusuchin85jusuchin85
authored
Restore documentation for FG PAT URL prefill feature (#61389)
1 parent 2458331 commit 3bb0e43

1 file changed

Lines changed: 164 additions & 0 deletions

File tree

‎content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,170 @@ For more information about best practices, see [AUTOTITLE](/rest/overview/keepin
117117

118118
If you selected an organization as the resource owner and the organization requires approval for {% data variables.product.pat_v2 %}s, then your token will be marked as `pending` until it is reviewed by an organization administrator. Your token will only be able to read public resources until it is approved. If you are an owner of the organization, your request is automatically approved. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization).
119119

120+
{% ifversion fpt or ghec %}
121+
122+
## Pre-filling {% data variables.product.pat_v2 %} details using URL parameters
123+
124+
You can share templates for a {% data variables.product.pat_v2 %} via links. By directing users to token creation with relevant fields already completed, you make it easier to automate workflows and improve their developer experience.
125+
126+
Each supported field can be set using a specific query parameter. All parameters are optional and validated by the token generation form to ensure that the combinations of permissions and resource owner make sense.
127+
128+
Here is an example URL template, with line breaks for legibility:
129+
130+
```http copy
131+
https://github.com/settings/personal-access-tokens/new
132+
?name=Repo-reading+token
133+
&description=Just+contents:read
134+
&target_name=octodemo
135+
&expires_in=45
136+
&contents=read
137+
```
138+
139+
Try the URL to create a token with `contents:read` and `metadata:read`, with the given name and description and an expiration date 45 days in the future. You'll see an error message indicating `Cannot find the specified resource owner: octodemo` because you're not a member of the `octodemo` organization.
140+
141+
Below are some example URLs that generate the tokens we see most often:
142+
143+
* [Read repository contents](https://github.com/settings/personal-access-tokens/new?name=Repo-reading+token&description=Just+contents:read&contents=read)
144+
* [Push access to repositories](https://github.com/settings/personal-access-tokens/new?name=Repo-writing+token&description=Just+contents:write&contents=write)
145+
* [{% data variables.product.prodname_github_models %} access](https://github.com/settings/personal-access-tokens/new?name=GitHub+Models+token&description=Used%20to%20call%20GitHub%20Models%20APIs%20to%20easily%20run%20LLMs%3A%20https%3A%2F%2Fdocs.github.com%2Fgithub-models%2Fquickstart%23step-2-make-an-api-call&user_models=read)<!-- markdownlint-disable-line search-replace Custom rule -->
146+
* [Update code and open a pull request](https://github.com/settings/personal-access-tokens/new?name=Core-loop+token&description=Write%20code%20and%20push%20it%20to%20main%21%20Includes%20permission%20to%20edit%20workflow%20files%20for%20Actions%20-%20remove%20%60workflows%3Awrite%60%20if%20you%20don%27t%20need%20to%20do%20that&contents=write&pull_requests=write&workflows=write)
147+
* [Manage {% data variables.product.prodname_copilot_short %} licenses in an organization](https://github.com/settings/personal-access-tokens/new?name=Core-loop+token&description=Enable%20or%20disable%20copilot%20access%20for%20users%20with%20the%20Seat%20Management%20APIs%3A%20https%3A%2F%2Fdocs.github.com%2Frest%2Fcopilot%2Fcopilot-user-management%0ABe%20sure%20to%20select%20an%20organization%20for%20your%20resource%20owner%20below%21&organization_copilot_seat_management=write)<!-- markdownlint-disable-line search-replace Custom rule -->
148+
* [Make {% data variables.product.prodname_copilot_short %} requests](https://github.com/settings/personal-access-tokens/new?name=Copilot+requests+token&description=Make%20Copilot%20API%20requests%20on%20behalf%20of%20the%20user%2C%20consuming%20premium%20requests%3A%20https%3A%2F%2Fdocs.github.com%2Fcopilot%2Fconcepts%2Fbilling%2Fcopilot-requests&user_copilot_requests=read)<!-- markdownlint-disable-line search-replace Custom rule -->
149+
150+
### Supported query parameters
151+
152+
To create your own token template, follow the query parameter details provided in this table:
153+
154+
| Parameter | Type | Example Value | Valid Values | Description |
155+
| --- | --- | --- | --- | --- |
156+
| `name` | string | `Deploy%20Bot` | ≤ 40 characters, URL-encoded | Pre-fills the token's display name. |
157+
| `description` | string | `Used+for+deployments` | ≤ 1024 chars, URL-encoded | Pre-fills the description for the token. |
158+
| `target_name` | string | `octodemo` | User or organization slug | Sets the token's resource target. This is the owner of the repositories that the token will be able to access. If not provided, defaults to the current user's account. |
159+
| `expires_in` | integer | `30` or `none` | Integer between 1 and 366, or `none` | Days until expiration or `none` for non-expiring. If not provided, the default is 30 days, or less if the target has a token lifetime policy set. |
160+
| `<permission>` | string | `contents=read` | A series of permission and access levels. | The permissions the token should have. Permissions can be set to `read`, `write`, or `admin`, but not every permission supports each of those levels. |
161+
162+
### Permissions
163+
164+
To set a permission, use its name as a query parameter, with the value specifying the desired access level. Valid access levels are `read`, `write`, and `admin`, but not every permission supports every level — some are `read`-only, some are `write`-only, and only a few accept `admin`.
165+
166+
Combine multiple permissions in the form `&contents=read&pull_requests=write&...`, using as many as needed.
167+
168+
> [!TIP]
169+
> You do not need to include both `read` and `write` for a permission in your URL — `write` always includes `read`, and `admin` always includes `write`.
170+
171+
#### Account permissions
172+
173+
> [!IMPORTANT]
174+
> Account permissions can only be used when the current user is the resource owner.
175+
176+
| Parameter name | Display name | Access levels |
177+
| --- | --- | --- |
178+
| `blocking` | Block another user | `read`, `write` |
179+
| `codespaces_user_secrets` | {% data variables.product.prodname_codespaces %} user secrets | `read`, `write` |
180+
| `copilot_messages` | {% data variables.copilot.copilot_chat_short %} | `read` |
181+
| `copilot_editor_context` | {% data variables.product.prodname_copilot_short %} Editor Context | `read` |
182+
| `copilot_requests` | {% data variables.product.prodname_copilot_short %} requests | `write` |
183+
| `emails` | Email addresses | `read`, `write` |
184+
| `user_events` | Events | `read` |
185+
| `followers` | Followers | `read`, `write` |
186+
| `gpg_keys` | GPG keys | `read`, `write` |
187+
| `gists` | Gists | `write` |
188+
| `keys` | Git SSH keys | `read`, `write` |
189+
| `interaction_limits` | Interaction limits | `read`, `write` |
190+
| `knowledge_bases` | Knowledge bases | `read`, `write` |
191+
| `user_models` | Models | `read` |
192+
| `plan` | Plan | `read` |
193+
| `private_repository_invitations` | Private repository invitations | `read` |
194+
| `profile` | Profile | `write` |
195+
| `git_signing_ssh_public_keys` | SSH signing keys | `read`, `write` |
196+
| `starring` | Starring | `read`, `write` |
197+
| `watching` | Watching | `read`, `write` |
198+
199+
{% ifversion copilot %}
200+
201+
> [!NOTE]
202+
> The `copilot_requests` permission enables making {% data variables.product.prodname_copilot_short %} requests for the given user. These requests count towards the user's premium request allowance. Additional requests beyond the allowance incur overage billing. For more information about {% data variables.product.prodname_copilot_short %} requests and billing, see [AUTOTITLE](/copilot/concepts/billing/copilot-requests).
203+
204+
{% endif %}
205+
206+
#### Repository permissions
207+
208+
Repository permissions work for both user and organization resource owners.
209+
210+
| Parameter name | Display name | Access levels |
211+
| --- | --- | --- |
212+
| `actions` | Actions | `read`, `write` |
213+
| `administration` | Administration | `read`, `write` |
214+
| {% ifversion artifact-metadata %} |
215+
| `artifact_metadata` | Artifact metadata | `read`, `write` |
216+
| {% endif %} |
217+
| `attestations` | Attestations | `read`, `write` |
218+
| {% ifversion code-quality %} |
219+
| `code_quality` | Code quality | `read`, `write` |
220+
| {% endif %} |
221+
| `security_events` | Code scanning alerts | `read`, `write` |
222+
| `codespaces` | {% data variables.product.prodname_codespaces %} | `read`, `write` |
223+
| `codespaces_lifecycle_admin` | {% data variables.product.prodname_codespaces %} lifecycle admin | `read`, `write` |
224+
| `codespaces_metadata` | {% data variables.product.prodname_codespaces %} metadata | `read` |
225+
| `codespaces_secrets` | {% data variables.product.prodname_codespaces %} secrets | `write` |
226+
| `statuses` | Commit statuses | `read`, `write` |
227+
| `contents` | Contents | `read`, `write` |
228+
| `repository_custom_properties` | Custom properties | `read`, `write` |
229+
| `vulnerability_alerts` | {% data variables.product.prodname_dependabot_alerts %} | `read`, `write` |
230+
| `dependabot_secrets` | Dependabot secrets | `read`, `write` |
231+
| `deployments` | Deployments | `read`, `write` |
232+
| `discussions` | Discussions | `read`, `write` |
233+
| `environments` | Environments | `read`, `write` |
234+
| `issues` | Issues | `read`, `write` |
235+
| `merge_queues` | Merge queues | `read`, `write` |
236+
| `metadata` | Metadata | `read` |
237+
| `pages` | Pages | `read`, `write` |
238+
| `pull_requests` | Pull requests | `read`, `write` |
239+
| `repository_advisories` | Repository security advisories | `read`, `write` |
240+
| `secret_scanning_alerts` | {% data variables.product.prodname_secret_scanning_caps %} alerts | `read`, `write` |
241+
| `secrets` | Secrets | `read`, `write` |
242+
| `actions_variables` | Variables | `read`, `write` |
243+
| `repository_hooks` | Webhooks | `read`, `write` |
244+
| `workflows` | Workflows | `write` |
245+
246+
#### Organization permissions
247+
248+
> [!IMPORTANT]
249+
> Organization permissions can only be used if the resource owner is an organization.
250+
251+
| Parameter name | Display name | Access levels |
252+
| --- | --- | --- |
253+
| `organization_api_insights` | API Insights | `read` |
254+
| `organization_administration` | Administration | `read`, `write` |
255+
| `organization_user_blocking` | Blocking users | `read`, `write` |
256+
| `organization_campaigns` | Campaigns | `read`, `write` |
257+
| `organization_custom_org_roles` | Custom organization roles | `read`, `write` |
258+
| `organization_custom_properties` | Custom repository properties | `read`, `write`, `admin` |
259+
| `organization_custom_roles` | Custom repository roles | `read`, `write` |
260+
| `organization_events` | Events | `read` |
261+
| `organization_copilot_seat_management` | {% data variables.copilot.copilot_for_business %} | `read`, `write` |
262+
| `issue_types` | Issue Types | `read`, `write` |
263+
| `organization_knowledge_bases` | Knowledge bases | `read`, `write` |
264+
| `members` | Members | `read`, `write` |
265+
| `organization_models` | Models | `read` |
266+
| `organization_network_configurations` | Network configurations | `read`, `write` |
267+
| `organization_announcement_banners` | Organization announcement banners | `read`, `write` |
268+
| `organization_codespaces` | Organization {% data variables.product.prodname_codespaces %} | `read`, `write` |
269+
| `organization_codespaces_secrets` | Organization {% data variables.product.prodname_codespaces %} secrets | `read`, `write` |
270+
| `organization_codespaces_settings` | Organization {% data variables.product.prodname_codespaces %} settings | `read`, `write` |
271+
| `organization_dependabot_secrets` | Organization {% data variables.product.prodname_dependabot %} secrets | `read`, `write` |
272+
| `organization_code_scanning_dismissal_requests` | Organization dismissal requests for {% data variables.product.prodname_code_scanning %} | `read`, `write` |
273+
| `organization_private_registries` | Organization private registries | `read`, `write` |
274+
| `organization_plan` | Plan | `read` |
275+
| `organization_projects` | {% data variables.product.prodname_projects_v2 %} | `read`, `write`, `admin` |
276+
| `organization_secrets` | Secrets | `read`, `write` |
277+
| `organization_self_hosted_runners` | Self-hosted runners | `read`, `write` |
278+
| `team_discussions` | Team discussions | `read`, `write` |
279+
| `organization_actions_variables` | Variables | `read`, `write` |
280+
| `organization_hooks` | Webhooks | `read`, `write` |
281+
282+
{% endif %}
283+
120284
## Creating a {% data variables.product.pat_v1 %}
121285

122286
> [!NOTE]

0 commit comments

Comments
 (0)