From 24a7d1d9cbf865843eb500dd7eed73d3cb716039 Mon Sep 17 00:00:00 2001 From: Cynthia <106874594+CynthiaJoseph@users.noreply.github.com> Date: Fri, 22 Aug 2025 22:30:13 +0100 Subject: [PATCH 1/2] 28 days to 100 days (#57241) Co-authored-by: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com> --- .../measure-adoption/analyze-usage-over-time.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/copilot/tutorials/roll-out-at-scale/measure-adoption/analyze-usage-over-time.md b/content/copilot/tutorials/roll-out-at-scale/measure-adoption/analyze-usage-over-time.md index cf1d551b40a0..40ff9f7e359d 100644 --- a/content/copilot/tutorials/roll-out-at-scale/measure-adoption/analyze-usage-over-time.md +++ b/content/copilot/tutorials/roll-out-at-scale/measure-adoption/analyze-usage-over-time.md @@ -25,7 +25,7 @@ You can use the [AUTOTITLE](/rest/copilot/copilot-metrics) to see trends in how The API includes: -* Data for the last 28 days +* Data for the last 100 days * Numbers of active users and engaged users * Breakdowns by language and IDE * The option to view metrics for an enterprise, organization, or team @@ -125,7 +125,7 @@ In your terminal, you should see output with a JSON array like the following. ## 3. Store the data -To analyze trends over longer than 28 days, you will need to: +To analyze trends over longer than 100 days, you will need to: * Call the API daily, using a cron job or scheduled {% data variables.product.prodname_actions %} workflow. * Store data locally or with a database service such as MySQL. @@ -208,7 +208,7 @@ If you run the script again tomorrow, it should only save data for one new day t ## 4. Analyze trends -You can work with the data from the API to identify trends over the last 28 days or, if you've stored data from previous API calls, over a longer period. +You can work with the data from the API to identify trends over the last 100 days or, if you've stored data from previous API calls, over a longer period. ### Example From 5d8710e8c9d18d88b310d2b73796680b14b53228 Mon Sep 17 00:00:00 2001 From: Hirsch Singhal <1666363+hpsin@users.noreply.github.com> Date: Fri, 22 Aug 2025 16:13:18 -0700 Subject: [PATCH 2/2] Deeplinking for FG PAT creation details (#57039) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com> --- .../authenticate-with-github_token.md | 2 + ...egistering-a-github-app-from-a-manifest.md | 2 +- ...ering-a-github-app-using-url-parameters.md | 2 +- .../managing-your-personal-access-tokens.md | 140 ++++++++++++++++++ 4 files changed, 144 insertions(+), 2 deletions(-) diff --git a/content/actions/tutorials/authenticate-with-github_token.md b/content/actions/tutorials/authenticate-with-github_token.md index 45132fdfee23..9e2bea6a58d4 100644 --- a/content/actions/tutorials/authenticate-with-github_token.md +++ b/content/actions/tutorials/authenticate-with-github_token.md @@ -70,6 +70,8 @@ jobs: Use the `permissions` key in your workflow file to modify permissions for the `GITHUB_TOKEN` for an entire workflow or for individual jobs. This allows you to configure the minimum required permissions for a workflow or job. As a good security practice, you should grant the `GITHUB_TOKEN` the least required access. + To see the list of permissions available for use and their parameterized names, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#account-permissions). + The two workflow examples earlier in this article show the `permissions` key being used at the job level. ## Granting additional permissions diff --git a/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md b/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md index 00994f8d1d7b..15baf2cd58e3 100644 --- a/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md +++ b/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md @@ -67,7 +67,7 @@ The person registering the app will be redirected to a {% data variables.product `description` | `string` | A description of the {% data variables.product.prodname_github_app %}. `public` | `boolean` | Set to `true` when your {% data variables.product.prodname_github_app %} is available to the public or `false` when it is only accessible to the owner of the app. `default_events` | `array` | The list of [events](/webhooks-and-events/webhooks/webhook-events-and-payloads) the {% data variables.product.prodname_github_app %} subscribes to. -`default_permissions` | `object` | The set of permissions needed by the {% data variables.product.prodname_github_app %}. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`). For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app). +`default_permissions` | `object` | The set of permissions needed by the {% data variables.product.prodname_github_app %}. The format of the object uses the permission name for the key (for example, `issues`) and the access type for the value (for example, `write`). For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app). To see the list of permissions available for use and their parameterized names, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#account-permissions). `request_oauth_on_install` | `boolean` | Set to `true` to request the user to authorize the {% data variables.product.prodname_github_app %}, after the {% data variables.product.prodname_github_app %} is installed. `setup_on_update` | `boolean` | Set to `true` to redirect users to the `setup_url` after they update your {% data variables.product.prodname_github_app %} installation. diff --git a/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md b/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md index f86da1c7d2b4..06e54b50c5b1 100644 --- a/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md +++ b/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md @@ -74,7 +74,7 @@ For example, to select "Read & write" permissions in the user interface for `con If the owning account is not an enterprise or an enterprise-owned organization, it cannot request enterprise permissions.{% endif %} -For more information about permissions and {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). +For more information about permissions and {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). To see the list of permissions available for use and their parameterized names, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#account-permissions). ## {% data variables.product.prodname_github_app %} webhook events diff --git a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md b/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md index 2ae1d330d905..1fdc00658e46 100644 --- a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md +++ b/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md @@ -118,6 +118,146 @@ For more information about best practices, see [AUTOTITLE](/rest/overview/keepin 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). +### Pre-filling {% data variables.product.pat_v2 %} details using URL parameters + +You can share templates for a {% data variables.product.pat_v2 %} via links. Storing token details this way makes it easier to automate workflows and improve your developer experience by directing users to token creation with relevant fields already completed. + +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 makes sense. + +An example URL template is shown here, with line breaks for legibility: + +```http copy +https://github.com/settings/personal-access-tokens/new + ?name=Repo-reading+token + &description=Just+contents:read + &target_name=octodemo + &expires_in=45 + &contents=read +``` + +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. + +Below are some example URLs that generate the tokens we see most often: + +* [Read repo contents](https://github.com/settings/personal-access-tokens/new?name=Repo-reading+token&description=Just+contents:read&contents=read) +* [Push access to repos](https://github.com/settings/personal-access-tokens/new?name=Repo-writing+token&description=Just+contents:write&contents=write) +* [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) +* [Update code and open a PR](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) +* [Manage Copilot 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) + +#### Supported Query Parameters + +To create your own token template, follow the query parameter details provided in this table: + +| Parameter | Type | Example Value | Valid Values | Description | +|----------------|--------|------------------|--------------|-----------------------| +| `name` | string | `Deploy%20Bot` | ≤ 40 characters, URL-encoded | Pre-fills the token’s display name. | +| `description` | string | `Used+for+deployments` | ≤ 1024 chars, URL-encoded | Pre-fills the description for the token. | +| `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. | +| `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. | +| `` | 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. | + +#### Permissions + +Each supported permission is set using its name as a query parameter, with the value specifying the desired access level. Valid access levels are `read`, `write`, and `admin`. Some permissions only support `read`, some only support `write`, and only a few have `admin`. Use as many permissions as needed, in the form `&contents=read&pull_requests=write&...`. + +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`. + +##### Account Permissions + +Account permissions are only used when the current user is set as the resource owner. + +| Parameter name | Display name | Access levels | +|---|---|---| +| `blocking` | Block another user | `read`, `write` | +| `codespaces_user_secrets` | Codespaces user secrets | `read`, `write` | +| `copilot_messages` | Copilot Chat | `read` | +| `copilot_editor_context` | Copilot Editor Context | `read` | +| `emails` | Email addresses | `read`, `write` | +| `user_events` | Events | `read` | +| `followers` | Followers | `read`, `write` | +| `gpg_keys` | GPG keys | `read`, `write` | +| `gists` | Gists | `write` | +| `keys` | Git SSH keys | `read`, `write` | +| `interaction_limits` | Interaction limits | `read`, `write` | +| `knowledge_bases` | Knowledge bases | `read`, `write` | +| `user_models` | Models | `read` | +| `plan` | Plan | `read` | +| `private_repository_invitations` | Private repository invitations | `read` | +| `profile` | Profile | `write` | +| `git_signing_ssh_public_keys` | SSH signing keys | `read`, `write` | +| `starring` | Starring | `read`, `write` | +| `watching` | Watching | `read`, `write` | + +##### Repository Permissions + +Repository permissions work for both user and organization resource owners. + +| Parameter name | Display name | Access levels | +|---|---|---| +| `actions` | Actions | `read`, `write` | +| `administration` | Administration | `read`, `write` | +| `attestations` | Attestations | `read`, `write` | +| `security_events` | Code scanning alerts | `read`, `write` | +| `codespaces` | Codespaces | `read`, `write` | +| `codespaces_lifecycle_admin` | Codespaces lifecycle admin | `read`, `write` | +| `codespaces_metadata` | Codespaces metadata | `read` | +| `codespaces_secrets` | Codespaces secrets | `write` | +| `statuses` | Commit statuses | `read`, `write` | +| `contents` | Contents | `read`, `write` | +| `repository_custom_properties` | Custom properties | `read`, `write` | +| `vulnerability_alerts` | Dependabot alerts | `read`, `write` | +| `dependabot_secrets` | Dependabot secrets | `read`, `write` | +| `deployments` | Deployments | `read`, `write` | +| `discussions` | Discussions | `read`, `write` | +| `environments` | Environments | `read`, `write` | +| `issues` | Issues | `read`, `write` | +| `merge_queues` | Merge queues | `read`, `write` | +| `metadata` | Metadata | `read` | +| `pages` | Pages | `read`, `write` | +| `pull_requests` | Pull requests | `read`, `write` | +| `repository_advisories` | Repository security advisories | `read`, `write` | +| `secret_scanning_alerts` | Secret scanning alerts | `read`, `write` | +| `secrets` | Secrets | `read`, `write` | +| `actions_variables` | Variables | `read`, `write` | +| `repository_hooks` | Webhooks | `read`, `write` | +| `workflows` | Workflows | `write` | + +##### Organization Permissions + +Organization permissions can only be used if the resource owner is an organization. + +| Parameter name | Display name | Access levels | +|---|---|---| +| `organization_api_insights` | API Insights | `read` | +| `organization_administration` | Administration | `read`, `write` | +| `organization_user_blocking` | Blocking users | `read`, `write` | +| `organization_campaigns` | Campaigns | `read`, `write` | +| `organization_custom_org_roles` | Custom organization roles | `read`, `write` | +| `organization_custom_properties` | Custom repository properties | `read`, `write`, `admin` | +| `organization_custom_roles` | Custom repository roles | `read`, `write` | +| `organization_events` | Events | `read` | +| `organization_copilot_seat_management` | GitHub Copilot Business | `read`, `write` | +| `issue_types` | Issue Types | `read`, `write` | +| `organization_knowledge_bases` | Knowledge bases | `read`, `write` | +| `members` | Members | `read`, `write` | +| `organization_models` | Models | `read` | +| `organization_network_configurations` | Network configurations | `read`, `write` | +| `organization_announcement_banners` | Organization announcement banners | `read`, `write` | +| `organization_codespaces` | Organization codespaces | `read`, `write` | +| `organization_codespaces_secrets` | Organization codespaces secrets | `read`, `write` | +| `organization_codespaces_settings` | Organization codespaces settings | `read`, `write` | +| `organization_dependabot_secrets` | Organization dependabot secrets | `read`, `write` | +| `organization_code_scanning_dismissal_requests` | Code scanning dismissal requests | `read`, `write` | +| `organization_private_registries` | Private registries | `read`, `write` | +| `organization_plan` | Plan | `read` | +| `organization_projects` | Projects | `read`, `write`, `admin` | +| `organization_secrets` | Secrets | `read`, `write` | +| `organization_self_hosted_runners` | Self-hosted runners | `read`, `write` | +| `team_discussions` | Team discussions | `read`, `write` | +| `organization_actions_variables` | Variables | `read`, `write` | +| `organization_hooks` | Webhooks | `read`, `write` | + ## Creating a {% data variables.product.pat_v1 %} > [!NOTE]