diff --git a/content/actions/concepts/workflows-and-actions/about-custom-actions.md b/content/actions/concepts/workflows-and-actions/about-custom-actions.md index 45117d387ad6..f561bed5743d 100644 --- a/content/actions/concepts/workflows-and-actions/about-custom-actions.md +++ b/content/actions/concepts/workflows-and-actions/about-custom-actions.md @@ -83,7 +83,7 @@ Many people access {% data variables.product.github %} at a domain other than {% To ensure that your action is compatible with other platforms, do not use any hard-coded references to API URLs such as `https://api.github.com`. Instead, you can: -* Use environment variables (see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables)): +* Use environment variables (see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables)): * For the REST API, use the `GITHUB_API_URL` environment variable. * For GraphQL, use the `GITHUB_GRAPHQL_URL` environment variable. diff --git a/content/actions/concepts/workflows-and-actions/contexts.md b/content/actions/concepts/workflows-and-actions/contexts.md new file mode 100644 index 000000000000..8732c87b63b2 --- /dev/null +++ b/content/actions/concepts/workflows-and-actions/contexts.md @@ -0,0 +1,53 @@ +--- +title: Contexts +shortTitle: Contexts +intro: 'Learn about contexts in {% data variables.product.prodname_actions %}.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +type: overview +topics: + - Actions + - Workflows +--- + +## About contexts + +{% data reusables.actions.actions-contexts-about-description %} Each context is an object that contains properties, which can be strings or other objects. + +{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [matrix](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix). + +You can access contexts using the expression syntax. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). + +{% raw %} +`${{ }}` +{% endraw %} + +{% data reusables.actions.context-injection-warning %} + +## Determining when to use contexts + +{% data variables.product.prodname_actions %} includes a collection of variables called _contexts_ and a similar collection of variables called _default variables_. These variables are intended for use at different points in the workflow: + +* **Default environment variables:** These environment variables exist only on the runner that is executing your job. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). +* **Contexts:** You can use most contexts at any point in your workflow, including when _default variables_ would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to a runner for execution; this allows you to use a context with the conditional `if` keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the runner that is executing the job, such as `runner.os`. For details of where you can use various contexts within a workflow, see [AUTOTITLE](/actions/reference/accessing-contextual-information-about-workflow-runs#context-availability). + +The following example demonstrates how these different types of variables can be used together in a job: + +{% raw %} + +```yaml copy +name: CI +on: push +jobs: + prod-check: + if: ${{ github.ref == 'refs/heads/main' }} + runs-on: ubuntu-latest + steps: + - run: echo "Deploying to production server on branch $GITHUB_REF" +``` + +{% endraw %} + +In this example, the `if` statement checks the [`github.ref`](/actions/learn-github-actions/contexts#github-context) context to determine the current branch name; if the name is `refs/heads/main`, then the subsequent steps are executed. The `if` check is processed by {% data variables.product.prodname_actions %}, and the job is only sent to the runner if the result is `true`. Once the job is sent to the runner, the step is executed and refers to the [`$GITHUB_REF`](/actions/learn-github-actions/variables#default-environment-variables) variable from the runner. diff --git a/content/actions/concepts/workflows-and-actions/index.md b/content/actions/concepts/workflows-and-actions/index.md index ba56fcb55944..48b0f931e38b 100644 --- a/content/actions/concepts/workflows-and-actions/index.md +++ b/content/actions/concepts/workflows-and-actions/index.md @@ -7,8 +7,10 @@ versions: ghec: '*' children: - /about-workflows + - /variables - /avoiding-duplication - /about-custom-actions + - /contexts - /about-monitoring-workflows - /notifications-for-workflow-runs - /about-troubleshooting-workflows diff --git a/content/actions/concepts/workflows-and-actions/variables.md b/content/actions/concepts/workflows-and-actions/variables.md new file mode 100644 index 000000000000..5360a6585448 --- /dev/null +++ b/content/actions/concepts/workflows-and-actions/variables.md @@ -0,0 +1,28 @@ +--- +title: Variables +intro: 'Learn about variables in {% data variables.product.prodname_actions %} workflows.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +type: overview +topics: + - Action development + - Fundamentals +--- + +## About + +Variables provide a way to store and reuse non-sensitive configuration information. You can store any configuration data such as compiler flags, usernames, or server names as variables. Variables are interpolated on the runner machine that runs your workflow. Commands that run in actions or workflow steps can create, read, and modify variables. + +You can set your own custom variables or use the default environment variables that {% data variables.product.prodname_dotcom %} sets automatically. + +You can set a custom variable in two ways. + +* To define an environment variable for use in a single workflow, you can use the `env` key in the workflow file. For more information, see [Defining environment variables for a single workflow](/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#defining-environment-variables-for-a-single-workflow). +* To define a configuration variable across multiple workflows, you can define it at the organization, repository, or environment level. For more information, see [Defining configuration variables for multiple workflows](/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#defining-configuration-variables-for-multiple-workflows). + +> [!WARNING] +> By default, variables render unmasked in your build outputs. If you need greater security for sensitive information, such as passwords, use secrets instead. For more information, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). + +For reference documentation, see [AUTOTITLE](/actions/reference/variables-reference). diff --git a/content/actions/how-tos/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md b/content/actions/how-tos/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md index 09ebe753af48..9d631fb0ec21 100644 --- a/content/actions/how-tos/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md +++ b/content/actions/how-tos/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md @@ -27,7 +27,7 @@ The following scripting languages are supported: Your custom scripts can use the following features: -* **Variables:** Scripts have access to the default variables. The full webhook event payload can be found in `GITHUB_EVENT_PATH`. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). +* **Variables:** Scripts have access to the default variables. The full webhook event payload can be found in `GITHUB_EVENT_PATH`. For more information, see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables). * **Workflow commands:** Scripts can use workflow commands. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions). Scripts can also use environment files. For more information, see [Environment files](/actions/using-workflows/workflow-commands-for-github-actions#environment-files). Your script files must use a file extension for the relevant language, such as `.sh` or `.ps1`, in order to run successfully. diff --git a/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md b/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md index cc89a5236fca..6305b64eee24 100644 --- a/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md +++ b/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md @@ -67,7 +67,7 @@ For more information about the tools and packages available on {% data variables CircleCI and {% data variables.product.prodname_actions %} support setting variables in the configuration file and creating secrets using the CircleCI or {% data variables.product.github %} UI. -For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). +For more information, see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). ## Caching diff --git a/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md b/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md index 889aff0c0e7b..3a83fc7bf476 100644 --- a/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md +++ b/content/actions/how-tos/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md @@ -50,7 +50,7 @@ Travis CI lets you set variables and share them between stages. Similarly, {% da ### Default variables -Travis CI and {% data variables.product.prodname_actions %} both include default environment variables that you can use in your YAML files. For {% data variables.product.prodname_actions %}, you can see these listed in [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). +Travis CI and {% data variables.product.prodname_actions %} both include default environment variables that you can use in your YAML files. For {% data variables.product.prodname_actions %}, you can see these listed in [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables). ### Parallel job processing diff --git a/content/actions/how-tos/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners.md b/content/actions/how-tos/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners.md index 8fc01eedb108..8c05929b3d57 100644 --- a/content/actions/how-tos/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners.md +++ b/content/actions/how-tos/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners.md @@ -231,7 +231,7 @@ To ensure proper communications for {% data variables.product.github %}-hosted r | `workspace` | `GITHUB_WORKSPACE` | Actions and shell commands execute in this directory. An action can modify the contents of this directory, which subsequent actions can access. | | `workflow/event.json` | `GITHUB_EVENT_PATH` | The `POST` payload of the webhook event that triggered the workflow. {% data variables.product.prodname_dotcom %} rewrites this each time an action executes to isolate file content between actions. -For a list of the environment variables {% data variables.product.prodname_dotcom %} creates for each workflow, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). +For a list of the environment variables {% data variables.product.prodname_dotcom %} creates for each workflow, see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables). ### Docker container filesystem diff --git a/content/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables.md b/content/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables.md index e43cff7da9f2..0d03e26681eb 100644 --- a/content/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables.md +++ b/content/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables.md @@ -17,22 +17,6 @@ versions: ghec: '*' --- -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About variables - -Variables provide a way to store and reuse non-sensitive configuration information. You can store any configuration data such as compiler flags, usernames, or server names as variables. Variables are interpolated on the runner machine that runs your workflow. Commands that run in actions or workflow steps can create, read, and modify variables. - -You can set your own custom variables or use the default environment variables that {% data variables.product.prodname_dotcom %} sets automatically. For more information, see [Default environment variables](#default-environment-variables). - -You can set a custom variable in two ways. - -* To define an environment variable for use in a single workflow, you can use the `env` key in the workflow file. For more information, see [Defining environment variables for a single workflow](#defining-environment-variables-for-a-single-workflow). -* To define a configuration variable across multiple workflows, you can define it at the organization, repository, or environment level. For more information, see [Defining configuration variables for multiple workflows](#defining-configuration-variables-for-multiple-workflows). - -> [!WARNING] -> By default, variables render unmasked in your build outputs. If you need greater security for sensitive information, such as passwords, use secrets instead. For more information, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). - ## Defining environment variables for a single workflow To set a custom environment variable for a single workflow, you can define it using the `env` key in the workflow file. The scope of a custom variable set by this method is limited to the element in which it is defined. You can define variables that are scoped for: @@ -72,13 +56,6 @@ The commands in the `run` steps of a workflow, or a referenced action, are proce Because runner environment variable interpolation is done after a workflow job is sent to a runner machine, you must use the appropriate syntax for the shell that's used on the runner. In this example, the workflow specifies `ubuntu-latest`. By default, Linux runners use the bash shell, so you must use the syntax `$NAME`. By default, Windows runners use PowerShell, so you would use the syntax `$env:NAME`. For more information about shells, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell). -### Naming conventions for environment variables - -When you set an environment variable, you cannot use any of the default environment variable names. For a complete list of default environment variables, see [Default environment variables](#default-environment-variables) below. If you attempt to override the value of one of these default variables, the assignment is ignored. - -> [!NOTE] -> You can list the entire set of environment variables that are available to a workflow step by using `run: env` in a step and then examining the output for the step. - ## Defining configuration variables for multiple workflows You can create configuration variables for use across multiple workflows, and can define them at either the [organization](#creating-configuration-variables-for-an-organization), [repository](#creating-configuration-variables-for-a-repository), or [environment](#creating-configuration-variables-for-an-environment) level. @@ -87,18 +64,6 @@ For example, you can use configuration variables to set default values for param When you define configuration variables, they are automatically available in the `vars` context. For more information, see [Using the `vars` context to access configuration variable values](#using-the-vars-context-to-access-configuration-variable-values). -### Configuration variable precedence - -If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence. For example, if an organization-level variable has the same name as a repository-level variable, then the repository-level variable takes precedence. Similarly, if an organization, repository, and environment all have a variable with the same name, the environment-level variable takes precedence. - -For reusable workflows, the variables from the caller workflow's repository are used. Variables from the repository that contains the called workflow are not made available to the caller workflow. - -### Naming conventions for configuration variables - -The following rules apply to configuration variable names: - -{% data reusables.actions.actions-secrets-and-variables-naming %} - ### Creating configuration variables for a repository {% data reusables.actions.permissions-statement-secrets-variables-repository %} @@ -143,40 +108,6 @@ The following rules apply to configuration variable names: 1. From the **Repository access** dropdown list, choose an access policy. 1. Click **Add variable**. -### Limits for configuration variables - -{% ifversion ghes %} - -Individual variables are limited to 48 KB in size. - -You can store up to 1,000 organization variables, 500 variables per repository, and 100 variables per environment. The total combined size limit for organization and repository variables is 10 MB per workflow run. - -A workflow created in a repository can access the following number of variables: - -* Up to 500 repository variables, if the total size of repository variables is less than 10 MB. If the total size of repository variables exceeds 10 MB, only the repository variables that fall below the limit will be available (as sorted alphabetically by variable name). -* Up to 1,000 organization variables, if the total combined size of repository and organization variables is less than 10 MB. If the total combined size of organization and repository variables exceeds 10 MB, only the organization variables that fall below that limit will be available (after accounting for repository variables and as sorted alphabetically by variable name). -* Up to 100 environment-level variables. - -> [!NOTE] -> Environment-level variables do not count toward the 10 MB total size limit. If you exceed the combined size limit for repository and organization variables and still need additional variables, you can use an environment and define additional variables in the environment. - -{% else %} - -Individual variables are limited to 48 KB in size. - -You can store up to 1,000 organization variables, 500 variables per repository, and 100 variables per environment. The total combined size limit for organization and repository variables is 256 KB per workflow run. - -A workflow created in a repository can access the following number of variables: - -* Up to 500 repository variables, if the total size of repository variables is less than 256 KB. If the total size of repository variables exceeds 256 KB, only the repository variables that fall below the limit will be available (as sorted alphabetically by variable name). -* Up to 1,000 organization variables, if the total combined size of repository and organization variables is less than 256 KB. If the total combined size of organization and repository variables exceeds 256 KB, only the organization variables that fall below that limit will be available (after accounting for repository variables and as sorted alphabetically by variable name). -* Up to 100 environment-level variables. - -> [!NOTE] -> Environment-level variables do not count toward the 256 KB total size limit. If you exceed the combined size limit for repository and organization variables and still need additional variables, you can use an environment and define additional variables in the environment. - -{% endif %} - ## Using contexts to access variable values {% data reusables.actions.actions-contexts-about-description %} For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts). There are many other contexts that you can use for a variety of purposes in your workflows. For details of where you can use specific contexts within a workflow, see [AUTOTITLE](/actions/learn-github-actions/contexts#context-availability). @@ -229,13 +160,6 @@ run: echo "${{ env.Greeting }} ${{ env.First_Name }}. Today is ${{ env.DAY_OF_WE > [!NOTE] > Contexts are usually denoted using the dollar sign and curly braces, as {% raw %}`${{ context.property }}`{% endraw %}. In an `if` conditional, the {% raw %}`${{` and `}}`{% endraw %} are optional, but if you use them they must enclose the entire comparison statement, as shown above. -You will commonly use either the `env` or `github` context to access variable values in parts of the workflow that are processed before jobs are sent to runners. - -| Context | Use case | Example | -| --- | --- | --- | -| `env` | Reference custom variables defined in the workflow. | {% raw %}`${{ env.MY_VARIABLE }}`{% endraw %} | -| `github` | Reference information about the workflow run and the event that triggered the run. | {% raw %}`${{ github.repository }}`{% endraw %} | - {% data reusables.actions.context-injection-warning %} ### Using the `vars` context to access configuration variable values @@ -244,66 +168,6 @@ Configuration variables can be accessed across the workflow using `vars` context {% data reusables.actions.actions-vars-context-example-usage %} -## Default environment variables - -The default environment variables that {% data variables.product.prodname_dotcom %} sets are available to every step in a workflow. - -Because default environment variables are set by {% data variables.product.prodname_dotcom %} and not defined in a workflow, they are not accessible through the `env` context. However, most of the default variables have a corresponding, and similarly named, context property. For example, the value of the `GITHUB_REF` variable can be read during workflow processing using the {% raw %}`${{ github.ref }}`{% endraw %} context property. - -{% data reusables.actions.environment-variables-are-fixed %} For more information about setting environment variables, see [Defining environment variables for a single workflow](#defining-environment-variables-for-a-single-workflow) and [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). - -We strongly recommend that actions use variables to access the filesystem rather than using hardcoded file paths. {% data variables.product.prodname_dotcom %} sets variables for actions to use in all runner environments. - -| Variable | Description | -| ---------|------------ | -| `CI` | Always set to `true`. | -| `GITHUB_ACTION` | The name of the action currently running, or the [`id`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsid) of a step. For example, for an action, `__repo-owner_name-of-action-repo`.

{% data variables.product.prodname_dotcom %} removes special characters, and uses the name `__run` when the current step runs a script without an `id`. If you use the same script or action more than once in the same job, the name will include a suffix that consists of the sequence number preceded by an underscore. For example, the first script you run will have the name `__run`, and the second script will be named `__run_2`. Similarly, the second invocation of `actions/checkout` will be `actionscheckout2`. | -| `GITHUB_ACTION_PATH` | The path where an action is located. This property is only supported in composite actions. You can use this path to change directories to where the action is located and access other files in that same repository. For example, `/home/runner/work/_actions/repo-owner/name-of-action-repo/v1`. | -| `GITHUB_ACTION_REPOSITORY` | For a step executing an action, this is the owner and repository name of the action. For example, `actions/checkout`. | -| `GITHUB_ACTIONS` | Always set to `true` when {% data variables.product.prodname_actions %} is running the workflow. You can use this variable to differentiate when tests are being run locally or by {% data variables.product.prodname_actions %}. | -| `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. | -| `GITHUB_ACTOR_ID` | {% data reusables.actions.actor_id-description %} | -| `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.rest_url %}`. | -| `GITHUB_BASE_REF` | The name of the base ref or target branch of the pull request in a workflow run. This is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `main`. | -| `GITHUB_ENV` | The path on the runner to the file that sets variables from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_env_87406d6e-4979-4d42-98e1-3dab1f48b13a`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). | -| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. For example, `workflow_dispatch`. | -| `GITHUB_EVENT_PATH` | The path to the file on the runner that contains the full event webhook payload. For example, `/github/workflow/event.json`. | -| `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url %}`. | -| `GITHUB_HEAD_REF` | The head ref or source branch of the pull request in a workflow run. This property is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `feature-branch-1`. | -| `GITHUB_JOB` | The [job_id](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_id) of the current job. For example, `greeting_job`. | -| `GITHUB_OUTPUT` | The path on the runner to the file that sets the current step's outputs from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_output_a50ef383-b063-46d9-9157-57953fc9f3f0`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter). | -| `GITHUB_PATH` | The path on the runner to the file that sets system `PATH` variables from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/add_path_899b9445-ad4a-400c-aa89-249f18632cf5`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-system-path). | -| `GITHUB_REF` | {% data reusables.actions.ref-description %} | -| `GITHUB_REF_NAME` | {% data reusables.actions.ref_name-description %} | -| `GITHUB_REF_PROTECTED` | {% data reusables.actions.ref_protected-description %} | -| `GITHUB_REF_TYPE` | {% data reusables.actions.ref_type-description %} | -| `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. | -| `GITHUB_REPOSITORY_ID` | {% data reusables.actions.repository_id-description %} | -| `GITHUB_REPOSITORY_OWNER` | The repository owner's name. For example, `octocat`. | -| `GITHUB_REPOSITORY_OWNER_ID` | {% data reusables.actions.repository_owner_id-description %} | -| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. For example, `90`. | -| `GITHUB_RUN_ATTEMPT` | A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run. For example, `3`. | -| `GITHUB_RUN_ID` | {% data reusables.actions.run_id_description %} For example, `1658821493`. | -| `GITHUB_RUN_NUMBER` | {% data reusables.actions.run_number_description %} For example, `3`. | -| `GITHUB_SERVER_URL`| The URL of the {% data variables.product.github %} server. For example: `https://{% data variables.product.product_url %}`. | -| `GITHUB_SHA` | {% data reusables.actions.github_sha_description %} | -| `GITHUB_STEP_SUMMARY` | The path on the runner to the file that contains job summaries from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/_layout/_work/_temp/_runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). | -| `GITHUB_TRIGGERING_ACTOR` | {% data reusables.actions.github-triggering-actor-description %} | -| `GITHUB_WORKFLOW` | The name of the workflow. For example, `My test workflow`. If the workflow file doesn't specify a `name`, the value of this variable is the full path of the workflow file in the repository. | -| `GITHUB_WORKFLOW_REF` | {% data reusables.actions.workflow-ref-description %} | -| `GITHUB_WORKFLOW_SHA` | {% data reusables.actions.workflow-sha-description %} | -| `GITHUB_WORKSPACE` | The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. For example, `/home/runner/work/my-repo-name/my-repo-name`. | -| `RUNNER_ARCH` | {% data reusables.actions.runner-arch-description %} | -| `RUNNER_DEBUG` | {% data reusables.actions.runner-debug-description %} | -| `RUNNER_ENVIRONMENT` | {% data reusables.actions.runner-environment-description %} | -| `RUNNER_NAME` | {% data reusables.actions.runner-name-description %} For example, `Hosted Agent` | -| `RUNNER_OS` | {% data reusables.actions.runner-os-description %} For example, `Windows` | -| `RUNNER_TEMP` | {% data reusables.actions.runner-temp-directory-description %} For example, `D:\a\_temp` | -| `RUNNER_TOOL_CACHE` | {% data reusables.actions.runner-tool-cache-description %} For example, `C:\hostedtoolcache\windows` | - -> [!NOTE] -> If you need to use a workflow run's URL from within a job, you can combine these variables: `$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID` - ## Detecting the operating system You can write a single workflow file that can be used for different operating systems by using the `RUNNER_OS` default environment variable and the corresponding context property {% raw %}`${{ runner.os }}`{% endraw %}. For example, the following workflow could be run successfully if you changed the operating system from `macos-latest` to `windows-latest` without having to alter the syntax of the environment variables, which differs depending on the shell being used by the runner. diff --git a/content/actions/reference/accessing-contextual-information-about-workflow-runs.md b/content/actions/reference/contexts-reference.md similarity index 97% rename from content/actions/reference/accessing-contextual-information-about-workflow-runs.md rename to content/actions/reference/contexts-reference.md index bc51ab2c77a1..81a9fc9fd659 100644 --- a/content/actions/reference/accessing-contextual-information-about-workflow-runs.md +++ b/content/actions/reference/contexts-reference.md @@ -1,7 +1,7 @@ --- -title: Accessing contextual information about workflow runs -shortTitle: Contexts -intro: You can access context information in workflows and actions. +title: Contexts reference +shortTitle: Contexts reference +intro: 'Find information about contexts available in {% data variables.product.prodname_actions %} workflows, including available properties, access methods, and usage examples.' redirect_from: - /articles/contexts-and-expression-syntax-for-github-actions - /github/automating-your-workflow-with-github-actions/contexts-and-expression-syntax-for-github-actions @@ -11,27 +11,14 @@ redirect_from: - /actions/learn-github-actions/contexts - /actions/writing-workflows/choosing-what-your-workflow-does/contexts - /actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs + - /actions/reference/accessing-contextual-information-about-workflow-runs versions: fpt: '*' ghes: '*' ghec: '*' --- -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About contexts - -{% data reusables.actions.actions-contexts-about-description %} Each context is an object that contains properties, which can be strings or other objects. - -{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [matrix](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix). - -You can access contexts using the expression syntax. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -{% raw %} -`${{ }}` -{% endraw %} - -{% data reusables.actions.context-injection-warning %} +## Available contexts | Context name | Type | Description | |---------------|------|-------------| @@ -61,7 +48,7 @@ If you attempt to dereference a nonexistent property, it will evaluate to an emp {% data variables.product.prodname_actions %} includes a collection of variables called _contexts_ and a similar collection of variables called _default variables_. These variables are intended for use at different points in the workflow: -* **Default environment variables:** These environment variables exist only on the runner that is executing your job. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). +* **Default environment variables:** These environment variables exist only on the runner that is executing your job. For more information, see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables). * **Contexts:** You can use most contexts at any point in your workflow, including when _default variables_ would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to a runner for execution; this allows you to use a context with the conditional `if` keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the runner that is executing the job, such as `runner.os`. For details of where you can use various contexts within a workflow, see [Context availability](#context-availability). The following example demonstrates how these different types of variables can be used together in a job: @@ -81,7 +68,7 @@ jobs: {% endraw %} -In this example, the `if` statement checks the [`github.ref`](/actions/learn-github-actions/contexts#github-context) context to determine the current branch name; if the name is `refs/heads/main`, then the subsequent steps are executed. The `if` check is processed by {% data variables.product.prodname_actions %}, and the job is only sent to the runner if the result is `true`. Once the job is sent to the runner, the step is executed and refers to the [`$GITHUB_REF`](/actions/learn-github-actions/variables#default-environment-variables) variable from the runner. +In this example, the `if` statement checks the [`github.ref`](/actions/learn-github-actions/contexts#github-context) context to determine the current branch name; if the name is `refs/heads/main`, then the subsequent steps are executed. The `if` check is processed by {% data variables.product.prodname_actions %}, and the job is only sent to the runner if the result is `true`. Once the job is sent to the runner, the step is executed and refers to the [`$GITHUB_REF`](/actions/reference/variables-reference#default-environment-variables) variable from the runner. ### Context availability @@ -174,7 +161,7 @@ jobs: ## `github` context -The `github` context contains information about the workflow run and the event that triggered the run. You can also read most of the `github` context data in environment variables. For more information about environment variables, see [AUTOTITLE](/actions/learn-github-actions/variables). +The `github` context contains information about the workflow run and the event that triggered the run. You can read most of the `github` context data in environment variables. For more information about environment variables, see [AUTOTITLE](/actions/learn-github-actions/variables). {% data reusables.actions.github-context-warning %} {% data reusables.actions.context-injection-warning %} @@ -877,3 +864,7 @@ jobs: ``` {% endraw %} + +## Further reading + +* [AUTOTITLE](/actions/concepts/workflows-and-actions/contexts) diff --git a/content/actions/reference/dockerfile-support-for-github-actions.md b/content/actions/reference/dockerfile-support-for-github-actions.md index 0af23ff26430..11ef504f807b 100644 --- a/content/actions/reference/dockerfile-support-for-github-actions.md +++ b/content/actions/reference/dockerfile-support-for-github-actions.md @@ -25,7 +25,7 @@ Some Docker instructions interact with GitHub Actions, and an action's metadata ### USER -Docker actions must be run by the default Docker user (root). Do not use the `USER` instruction in your `Dockerfile`, because you won't be able to access the `GITHUB_WORKSPACE` directory. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables) and [USER reference](https://docs.docker.com/engine/reference/builder/#user) in the Docker documentation. +Docker actions must be run by the default Docker user (root). Do not use the `USER` instruction in your `Dockerfile`, because you won't be able to access the `GITHUB_WORKSPACE` directory. For more information, see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables) and [USER reference](https://docs.docker.com/engine/reference/builder/#user) in the Docker documentation. ### FROM @@ -39,7 +39,7 @@ These are some best practices when setting the `FROM` argument: ### WORKDIR -{% data variables.product.github %} sets the working directory path in the `GITHUB_WORKSPACE` environment variable. It's recommended to not use the `WORKDIR` instruction in your `Dockerfile`. Before the action executes, {% data variables.product.github %} will mount the `GITHUB_WORKSPACE` directory on top of anything that was at that location in the Docker image and set `GITHUB_WORKSPACE` as the working directory. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables) and the [WORKDIR reference](https://docs.docker.com/engine/reference/builder/#workdir) in the Docker documentation. +{% data variables.product.github %} sets the working directory path in the `GITHUB_WORKSPACE` environment variable. It's recommended to not use the `WORKDIR` instruction in your `Dockerfile`. Before the action executes, {% data variables.product.github %} will mount the `GITHUB_WORKSPACE` directory on top of anything that was at that location in the Docker image and set `GITHUB_WORKSPACE` as the working directory. For more information, see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables) and the [WORKDIR reference](https://docs.docker.com/engine/reference/builder/#workdir) in the Docker documentation. ### ENTRYPOINT diff --git a/content/actions/reference/index.md b/content/actions/reference/index.md index d219a80fda5b..53fa0fb84399 100644 --- a/content/actions/reference/index.md +++ b/content/actions/reference/index.md @@ -1,7 +1,7 @@ --- title: Reference for GitHub Actions shortTitle: Reference -intro: "Find information to apply to your work with GitHub Actions." +intro: Find information to apply to your work with GitHub Actions. versions: fpt: '*' ghes: '*' @@ -10,8 +10,9 @@ children: - /workflow-syntax-for-github-actions - /events-that-trigger-workflows - /workflow-commands-for-github-actions + - /variables-reference - /evaluate-expressions-in-workflows-and-actions - - /accessing-contextual-information-about-workflow-runs + - /contexts-reference - /metadata-syntax-for-github-actions - /actions-limits - /dockerfile-support-for-github-actions @@ -19,3 +20,4 @@ children: - /usage-limits-for-self-hosted-runners - /supplemental-arguments-and-settings --- + diff --git a/content/actions/reference/variables-reference.md b/content/actions/reference/variables-reference.md new file mode 100644 index 000000000000..f6c7b6031b1c --- /dev/null +++ b/content/actions/reference/variables-reference.md @@ -0,0 +1,137 @@ +--- +title: Variables reference +shortTitle: Variables reference +intro: 'Find information for supported variables, naming conventions, limits, and contexts in {% data variables.product.prodname_actions %} workflows.' +versions: + fpt: '*' + ghes: '*' + ghec: '*' +--- + +This article lists the supported variables you can use in {% data variables.product.prodname_actions %} workflows, including environment variables, configuration variables, and default variables provided by {% data variables.product.github %}. Use this reference to look up variable names, naming conventions, limits, and supported contexts when configuring your workflows. + +For more information about variables, see [AUTOTITLE](/actions/concepts/workflows-and-actions/variables). + +## Default environment variables + +The default environment variables that {% data variables.product.prodname_dotcom %} sets are available to every step in a workflow. + +Because default environment variables are set by {% data variables.product.prodname_dotcom %} and not defined in a workflow, they are not accessible through the `env` context. However, most of the default variables have a corresponding, and similarly named, context property. For example, the value of the `GITHUB_REF` variable can be read during workflow processing using the {% raw %}`${{ github.ref }}`{% endraw %} context property. + +{% data reusables.actions.environment-variables-are-fixed %} For more information about setting environment variables, see [AUTOTITLE](/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#defining-environment-variables-for-a-single-workflow) and [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). + +We strongly recommend that actions use variables to access the filesystem rather than using hardcoded file paths. {% data variables.product.prodname_dotcom %} sets variables for actions to use in all runner environments. + +| Variable | Description | +| ---------|------------ | +| `CI` | Always set to `true`. | +| `GITHUB_ACTION` | The name of the action currently running, or the [`id`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsid) of a step. For example, for an action, `__repo-owner_name-of-action-repo`.

{% data variables.product.prodname_dotcom %} removes special characters, and uses the name `__run` when the current step runs a script without an `id`. If you use the same script or action more than once in the same job, the name will include a suffix that consists of the sequence number preceded by an underscore. For example, the first script you run will have the name `__run`, and the second script will be named `__run_2`. Similarly, the second invocation of `actions/checkout` will be `actionscheckout2`. | +| `GITHUB_ACTION_PATH` | The path where an action is located. This property is only supported in composite actions. You can use this path to change directories to where the action is located and access other files in that same repository. For example, `/home/runner/work/_actions/repo-owner/name-of-action-repo/v1`. | +| `GITHUB_ACTION_REPOSITORY` | For a step executing an action, this is the owner and repository name of the action. For example, `actions/checkout`. | +| `GITHUB_ACTIONS` | Always set to `true` when {% data variables.product.prodname_actions %} is running the workflow. You can use this variable to differentiate when tests are being run locally or by {% data variables.product.prodname_actions %}. | +| `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. | +| `GITHUB_ACTOR_ID` | {% data reusables.actions.actor_id-description %} | +| `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.rest_url %}`. | +| `GITHUB_BASE_REF` | The name of the base ref or target branch of the pull request in a workflow run. This is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `main`. | +| `GITHUB_ENV` | The path on the runner to the file that sets variables from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_env_87406d6e-4979-4d42-98e1-3dab1f48b13a`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). | +| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. For example, `workflow_dispatch`. | +| `GITHUB_EVENT_PATH` | The path to the file on the runner that contains the full event webhook payload. For example, `/github/workflow/event.json`. | +| `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url %}`. | +| `GITHUB_HEAD_REF` | The head ref or source branch of the pull request in a workflow run. This property is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `feature-branch-1`. | +| `GITHUB_JOB` | The [job_id](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_id) of the current job. For example, `greeting_job`. | +| `GITHUB_OUTPUT` | The path on the runner to the file that sets the current step's outputs from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_output_a50ef383-b063-46d9-9157-57953fc9f3f0`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter). | +| `GITHUB_PATH` | The path on the runner to the file that sets system `PATH` variables from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/add_path_899b9445-ad4a-400c-aa89-249f18632cf5`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-system-path). | +| `GITHUB_REF` | {% data reusables.actions.ref-description %} | +| `GITHUB_REF_NAME` | {% data reusables.actions.ref_name-description %} | +| `GITHUB_REF_PROTECTED` | {% data reusables.actions.ref_protected-description %} | +| `GITHUB_REF_TYPE` | {% data reusables.actions.ref_type-description %} | +| `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. | +| `GITHUB_REPOSITORY_ID` | {% data reusables.actions.repository_id-description %} | +| `GITHUB_REPOSITORY_OWNER` | The repository owner's name. For example, `octocat`. | +| `GITHUB_REPOSITORY_OWNER_ID` | {% data reusables.actions.repository_owner_id-description %} | +| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. For example, `90`. | +| `GITHUB_RUN_ATTEMPT` | A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run. For example, `3`. | +| `GITHUB_RUN_ID` | {% data reusables.actions.run_id_description %} For example, `1658821493`. | +| `GITHUB_RUN_NUMBER` | {% data reusables.actions.run_number_description %} For example, `3`. | +| `GITHUB_SERVER_URL`| The URL of the {% data variables.product.github %} server. For example: `https://{% data variables.product.product_url %}`. | +| `GITHUB_SHA` | {% data reusables.actions.github_sha_description %} | +| `GITHUB_STEP_SUMMARY` | The path on the runner to the file that contains job summaries from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/_layout/_work/_temp/_runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). | +| `GITHUB_TRIGGERING_ACTOR` | {% data reusables.actions.github-triggering-actor-description %} | +| `GITHUB_WORKFLOW` | The name of the workflow. For example, `My test workflow`. If the workflow file doesn't specify a `name`, the value of this variable is the full path of the workflow file in the repository. | +| `GITHUB_WORKFLOW_REF` | {% data reusables.actions.workflow-ref-description %} | +| `GITHUB_WORKFLOW_SHA` | {% data reusables.actions.workflow-sha-description %} | +| `GITHUB_WORKSPACE` | The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. For example, `/home/runner/work/my-repo-name/my-repo-name`. | +| `RUNNER_ARCH` | {% data reusables.actions.runner-arch-description %} | +| `RUNNER_DEBUG` | {% data reusables.actions.runner-debug-description %} | +| `RUNNER_ENVIRONMENT` | {% data reusables.actions.runner-environment-description %} | +| `RUNNER_NAME` | {% data reusables.actions.runner-name-description %} For example, `Hosted Agent` | +| `RUNNER_OS` | {% data reusables.actions.runner-os-description %} For example, `Windows` | +| `RUNNER_TEMP` | {% data reusables.actions.runner-temp-directory-description %} For example, `D:\a\_temp` | +| `RUNNER_TOOL_CACHE` | {% data reusables.actions.runner-tool-cache-description %} For example, `C:\hostedtoolcache\windows` | + +> [!NOTE] +> If you need to use a workflow run's URL from within a job, you can combine these variables: `$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID` + +## Naming conventions for configuration variables + +The following rules apply to configuration variable names: + +{% data reusables.actions.actions-secrets-and-variables-naming %} + +## Naming conventions for environment variables + +When you set an environment variable, you cannot use any of the default environment variable names. For a complete list of default environment variables, see [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables) below. If you attempt to override the value of one of these default variables, the assignment is ignored. + +> [!NOTE] +> You can list the entire set of environment variables that are available to a workflow step by using `run: env` in a step and then examining the output for the step. + +## Configuration variable precedence + +If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence. For example, if an organization-level variable has the same name as a repository-level variable, then the repository-level variable takes precedence. Similarly, if an organization, repository, and environment all have a variable with the same name, the environment-level variable takes precedence. + +For reusable workflows, the variables from the caller workflow's repository are used. Variables from the repository that contains the called workflow are not made available to the caller workflow. + +## Limits for configuration variables + +{% ifversion ghes %} + +Individual variables are limited to 48 KB in size. + +You can store up to 1,000 organization variables, 500 variables per repository, and 100 variables per environment. The total combined size limit for organization and repository variables is 10 MB per workflow run. + +A workflow created in a repository can access the following number of variables: + +* Up to 500 repository variables, if the total size of repository variables is less than 10 MB. If the total size of repository variables exceeds 10 MB, only the repository variables that fall below the limit will be available (as sorted alphabetically by variable name). +* Up to 1,000 organization variables, if the total combined size of repository and organization variables is less than 10 MB. If the total combined size of organization and repository variables exceeds 10 MB, only the organization variables that fall below that limit will be available (after accounting for repository variables and as sorted alphabetically by variable name). +* Up to 100 environment-level variables. + +> [!NOTE] +> Environment-level variables do not count toward the 10 MB total size limit. If you exceed the combined size limit for repository and organization variables and still need additional variables, you can use an environment and define additional variables in the environment. + +{% else %} + +Individual variables are limited to 48 KB in size. + +You can store up to 1,000 organization variables, 500 variables per repository, and 100 variables per environment. The total combined size limit for organization and repository variables is 256 KB per workflow run. + +A workflow created in a repository can access the following number of variables: + +* Up to 500 repository variables, if the total size of repository variables is less than 256 KB. If the total size of repository variables exceeds 256 KB, only the repository variables that fall below the limit will be available (as sorted alphabetically by variable name). +* Up to 1,000 organization variables, if the total combined size of repository and organization variables is less than 256 KB. If the total combined size of organization and repository variables exceeds 256 KB, only the organization variables that fall below that limit will be available (after accounting for repository variables and as sorted alphabetically by variable name). +* Up to 100 environment-level variables. + +> [!NOTE] +> Environment-level variables do not count toward the 256 KB total size limit. If you exceed the combined size limit for repository and organization variables and still need additional variables, you can use an environment and define additional variables in the environment. + +{% endif %} + +## Supported contexts + +You will commonly use either the `env` or `github` context to access variable values in parts of the workflow that are processed before jobs are sent to runners. + +> [!WARNING] Do not print the `github` context to logs. It contains sensitive information. + +| Context | Use case | Example | +| --- | --- | --- | +| `env` | Reference custom variables defined in the workflow. | {% raw %}`${{ env.MY_VARIABLE }}`{% endraw %} | +| `github` | Reference information about the workflow run and the event that triggered the run. | {% raw %}`${{ github.repository }}`{% endraw %} | diff --git a/content/actions/reference/workflow-commands-for-github-actions.md b/content/actions/reference/workflow-commands-for-github-actions.md index babb3fc5ec64..5e89361efd3b 100644 --- a/content/actions/reference/workflow-commands-for-github-actions.md +++ b/content/actions/reference/workflow-commands-for-github-actions.md @@ -554,7 +554,7 @@ console.log("The running PID from the main action is: " + process.env.STATE_proc ## Environment files -During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files can be accessed and edited using GitHub's default environment variables. See [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). You will need to use UTF-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines. +During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files can be accessed and edited using GitHub's default environment variables. See [AUTOTITLE](/actions/reference/variables-reference#default-environment-variables). You will need to use UTF-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines. To use environment variables in a GitHub Action, you create or modify `.env` files using specific GitHub Actions commands. Here's how: diff --git a/content/rest/models/embeddings.md b/content/rest/models/embeddings.md new file mode 100644 index 000000000000..33749ba6a87b --- /dev/null +++ b/content/rest/models/embeddings.md @@ -0,0 +1,13 @@ +--- +title: REST API endpoints for model embeddings +shortTitle: Embeddings +intro: Use the REST API to work with embedding requests for models. +versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 + fpt: '*' +topics: + - API +autogenerated: rest +allowTitleToDifferFromFilename: true +--- + + diff --git a/content/rest/models/index.md b/content/rest/models/index.md index 4016dde81abe..962ba13228ce 100644 --- a/content/rest/models/index.md +++ b/content/rest/models/index.md @@ -6,7 +6,9 @@ autogenerated: rest allowTitleToDifferFromFilename: true children: - /catalog + - /embeddings - /inference versions: fpt: '*' --- + diff --git a/data/reusables/pages/www-and-apex-domain-recommendation.md b/data/reusables/pages/www-and-apex-domain-recommendation.md index f94b04d6d4ee..e6e809fdeba1 100644 --- a/data/reusables/pages/www-and-apex-domain-recommendation.md +++ b/data/reusables/pages/www-and-apex-domain-recommendation.md @@ -1 +1 @@ -If you are using an apex domain as your custom domain, we recommend also setting up a `www` subdomain. If you configure the correct records for each domain type through your DNS provider, {% data variables.product.prodname_pages %} will automatically create redirects between the domains. For example, if you configure `www.example.com` as the custom domain for your site, and you have {% data variables.product.prodname_pages %} DNS records set up for the apex and `www` domains, then `example.com` will redirect to `www.example.com`. Note that automatic redirects only apply to the `www` subdomain. Automatic redirects do not apply to any other subdomains, such as `blog`. +If you are using an apex domain as your custom domain, we recommend also setting up a `www` subdomain. If you configure the correct records for each domain type through your DNS provider, {% data variables.product.prodname_pages %} will automatically create redirects between the domains. For example, if you configure `www.example.com` as the custom domain for your site, and you have {% data variables.product.prodname_pages %} DNS records set up for the apex and `www` domains, then `example.com` will redirect to `www.example.com`. If you instead configure `example.com` as the custom domain, then `www.example.com` will redirect to `example.com`. Automatic redirects also apply to other subdomains, as `www.blog.example.com` will redirect to `blog.example.com` or vice versa. It is not possible to configure a domain that starts with `www.www.`. diff --git a/src/events/lib/schema.ts b/src/events/lib/schema.ts index 2c4efa7b92ed..302997ac7335 100644 --- a/src/events/lib/schema.ts +++ b/src/events/lib/schema.ts @@ -371,6 +371,10 @@ const search = { type: 'string', description: 'Any additional search context, such as component searched.', }, + search_client: { + type: 'string', + description: 'The client name identifier when the request is not from docs.github.com.', + }, }, } diff --git a/src/events/types.ts b/src/events/types.ts index 762dbc9a8df5..b66f5e30613b 100644 --- a/src/events/types.ts +++ b/src/events/types.ts @@ -104,6 +104,7 @@ export type EventPropsByType = { [EventType.search]: { search_query: string search_context?: string + search_client?: string } [EventType.searchResult]: { search_result_query: string diff --git a/src/frame/components/page-footer/SupportSection.tsx b/src/frame/components/page-footer/SupportSection.tsx index 45b70eb79ea2..0c6e7f34bec0 100644 --- a/src/frame/components/page-footer/SupportSection.tsx +++ b/src/frame/components/page-footer/SupportSection.tsx @@ -48,7 +48,12 @@ export const SupportSection = () => { )} > {showCopilotCTA && ( - + )} {showSurvey && } {showContribution && } diff --git a/src/github-apps/lib/config.json b/src/github-apps/lib/config.json index 8ba8e0d19d6f..712c9f3807c0 100644 --- a/src/github-apps/lib/config.json +++ b/src/github-apps/lib/config.json @@ -60,5 +60,5 @@ "2022-11-28" ] }, - "sha": "527d41e4237d9ad0bac93932fe1d2fb22f8d1b97" + "sha": "664cf25da36ebb8f97693e51663addaed26bbae5" } \ No newline at end of file diff --git a/src/rest/data/fpt-2022-11-28/schema.json b/src/rest/data/fpt-2022-11-28/schema.json index fe33f0c1f851..268a674bc93c 100644 --- a/src/rest/data/fpt-2022-11-28/schema.json +++ b/src/rest/data/fpt-2022-11-28/schema.json @@ -170558,6 +170558,10 @@ "httpStatusCode": "409", "description": "

Response if there is already a validation run in progress with a different default setup configuration

" }, + { + "httpStatusCode": "422", + "description": "

Response if the configuration change cannot be made because the repository is not in the required state

" + }, { "httpStatusCode": "503", "description": "

Service unavailable

" @@ -176098,7 +176102,7 @@ "type": "array of integers", "name": "selected_repository_ids", "in": "body", - "description": "

An array of repository IDs to detach from configurations.

" + "description": "

An array of repository IDs to detach from configurations. Up to 1000 IDs can be provided.

" } ], "progAccess": { @@ -388924,6 +388928,388 @@ ] } ], + "embeddings": [ + { + "serverUrl": "https://models.github.ai", + "verb": "post", + "requestPath": "/orgs/{org}/inference/embeddings", + "title": "Run an embedding request attributed to an organization", + "category": "models", + "subcategory": "embeddings", + "parameters": [ + { + "in": "query", + "required": false, + "name": "api-version", + "description": "

The API version to use. Optional, but required for some features.

", + "schema": { + "type": "string" + }, + "example": "2024-05-01-preview" + }, + { + "in": "path", + "name": "org", + "required": true, + "description": "

The organization login associated with the organization to which the request is to be attributed.

", + "schema": { + "type": "string" + } + } + ], + "bodyParameters": [ + { + "type": "string", + "name": "model", + "in": "body", + "description": "

ID of the specific model to use for the request. The model ID should be in the format of {publisher}/{model_name} where \"openai/text-embedding-3-small\" is an example of a model ID. You can find supported models in the catalog/models endpoint.

", + "isRequired": true + }, + { + "type": "string or array", + "name": "input", + "in": "body", + "description": "

Input text to embed, encoded as a string or array of strings. To embed multiple inputs in a single request, pass an array of strings. Each input must not exceed the max input tokens for the model, cannot be an empty string, and any array must be 2048 dimensions or less.

", + "isRequired": true + }, + { + "type": "string", + "name": "encoding_format", + "in": "body", + "description": "

The format to return the embeddings in. Can be either float or base64.

", + "enum": [ + "float", + "base64" + ], + "default": "float" + }, + { + "type": "integer", + "name": "dimensions", + "in": "body", + "description": "

The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.

" + }, + { + "type": "string", + "name": "user", + "in": "body", + "description": "

A unique identifier representing your end-user, which can help us to monitor and detect abuse.

" + } + ], + "codeExamples": [ + { + "key": "default", + "request": { + "contentType": "application/json", + "description": "Example", + "acceptHeader": "application/vnd.github.v3+json", + "bodyParameters": { + "model": "openai/text-embedding-3-small", + "input": [ + "The food was delicious and the waiter was very friendly.", + "I had a great time at the restaurant." + ] + }, + "parameters": { + "org": "ORG" + } + }, + "response": { + "statusCode": "200", + "contentType": "application/json", + "description": "", + "example": { + "object": "list", + "data": [ + { + "object": "embedding", + "index": 0, + "embedding": [ + 0.0023064255, + -0.009327292, + -0.0028842222 + ] + } + ], + "model": "openai/text-embedding-3-small", + "usage": { + "prompt_tokens": 8, + "total_tokens": 8 + } + }, + "schema": { + "title": "Embedding Response", + "description": "The response for an embedding request.", + "type": "object", + "properties": { + "object": { + "description": "The object type, which is always \"list\" for embedding responses.", + "type": "string", + "enum": [ + "list" + ] + }, + "data": { + "description": "A list of embedding objects.", + "type": "array", + "items": { + "title": "Embedding Object", + "description": "An embedding vector returned by the model.", + "type": "object", + "properties": { + "object": { + "description": "The object type, which is always \"embedding\".", + "type": "string", + "enum": [ + "embedding" + ] + }, + "index": { + "description": "The index of the embedding in the list of embeddings.", + "type": "integer" + }, + "embedding": { + "description": "The embedding vector, which is a list of floats.", + "type": "array", + "items": { + "type": "number" + } + } + }, + "required": [ + "object", + "index", + "embedding" + ] + } + }, + "model": { + "description": "The model used for the embedding.", + "type": "string" + }, + "usage": { + "description": "Usage statistics for the request.", + "type": "object", + "properties": { + "prompt_tokens": { + "description": "The number of tokens in the input.", + "type": "integer" + }, + "total_tokens": { + "description": "The total number of tokens processed.", + "type": "integer" + } + }, + "required": [ + "prompt_tokens", + "total_tokens" + ] + } + }, + "required": [ + "object", + "data", + "model", + "usage" + ] + } + } + } + ], + "previews": [], + "descriptionHTML": "

This endpoint allows you to run an embedding request attributed to a specific organization. You must be a member of the organization and have enabled models to use this endpoint.\nThe token used to authenticate must have the models: read permission if using a fine-grained PAT or GitHub App minted token.\nThe request body should contain the model ID and the input text(s) for the embedding request. The response will include the generated embeddings.

", + "statusCodes": [ + { + "httpStatusCode": "200", + "description": "

OK

" + } + ] + }, + { + "serverUrl": "https://models.github.ai", + "verb": "post", + "requestPath": "/inference/embeddings", + "title": "Run an embedding request", + "category": "models", + "subcategory": "embeddings", + "parameters": [ + { + "in": "query", + "required": false, + "name": "api-version", + "description": "

The API version to use. Optional, but required for some features.

", + "schema": { + "type": "string" + }, + "example": "2024-05-01-preview" + } + ], + "bodyParameters": [ + { + "type": "string", + "name": "model", + "in": "body", + "description": "

ID of the specific model to use for the request. The model ID should be in the format of {publisher}/{model_name} where \"openai/text-embedding-3-small\" is an example of a model ID. You can find supported models in the catalog/models endpoint.

", + "isRequired": true + }, + { + "type": "string or array", + "name": "input", + "in": "body", + "description": "

Input text to embed, encoded as a string or array of strings. To embed multiple inputs in a single request, pass an array of strings. Each input must not exceed the max input tokens for the model, cannot be an empty string, and any array must be 2048 dimensions or less.

", + "isRequired": true + }, + { + "type": "string", + "name": "encoding_format", + "in": "body", + "description": "

The format to return the embeddings in. Can be either float or base64.

", + "enum": [ + "float", + "base64" + ], + "default": "float" + }, + { + "type": "integer", + "name": "dimensions", + "in": "body", + "description": "

The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.

" + }, + { + "type": "string", + "name": "user", + "in": "body", + "description": "

A unique identifier representing your end-user, which can help us to monitor and detect abuse.

" + } + ], + "codeExamples": [ + { + "key": "default", + "request": { + "contentType": "application/json", + "description": "Example", + "acceptHeader": "application/vnd.github.v3+json", + "bodyParameters": { + "model": "openai/text-embedding-3-small", + "input": [ + "The food was delicious and the waiter was very friendly.", + "I had a great time at the restaurant." + ] + } + }, + "response": { + "statusCode": "200", + "contentType": "application/json", + "description": "", + "example": { + "object": "list", + "data": [ + { + "object": "embedding", + "index": 0, + "embedding": [ + 0.0023064255, + -0.009327292, + -0.0028842222 + ] + } + ], + "model": "openai/text-embedding-3-small", + "usage": { + "prompt_tokens": 8, + "total_tokens": 8 + } + }, + "schema": { + "title": "Embedding Response", + "description": "The response for an embedding request.", + "type": "object", + "properties": { + "object": { + "description": "The object type, which is always \"list\" for embedding responses.", + "type": "string", + "enum": [ + "list" + ] + }, + "data": { + "description": "A list of embedding objects.", + "type": "array", + "items": { + "title": "Embedding Object", + "description": "An embedding vector returned by the model.", + "type": "object", + "properties": { + "object": { + "description": "The object type, which is always \"embedding\".", + "type": "string", + "enum": [ + "embedding" + ] + }, + "index": { + "description": "The index of the embedding in the list of embeddings.", + "type": "integer" + }, + "embedding": { + "description": "The embedding vector, which is a list of floats.", + "type": "array", + "items": { + "type": "number" + } + } + }, + "required": [ + "object", + "index", + "embedding" + ] + } + }, + "model": { + "description": "The model used for the embedding.", + "type": "string" + }, + "usage": { + "description": "Usage statistics for the request.", + "type": "object", + "properties": { + "prompt_tokens": { + "description": "The number of tokens in the input.", + "type": "integer" + }, + "total_tokens": { + "description": "The total number of tokens processed.", + "type": "integer" + } + }, + "required": [ + "prompt_tokens", + "total_tokens" + ] + } + }, + "required": [ + "object", + "data", + "model", + "usage" + ] + } + } + } + ], + "previews": [], + "descriptionHTML": "

This endpoint allows you to run an embedding request. The token used to authenticate must have the models: read permission if using a fine-grained PAT or GitHub App minted token.\nThe request body should contain the model ID and the input text(s) for the embedding request. The response will include the generated embeddings.

", + "statusCodes": [ + { + "httpStatusCode": "200", + "description": "

OK

" + } + ] + } + ], "inference": [ { "serverUrl": "https://models.github.ai", @@ -389600,386 +389986,6 @@ "description": "

OK

" } ] - }, - { - "serverUrl": "https://models.github.ai", - "verb": "post", - "requestPath": "/orgs/{org}/inference/embeddings", - "title": "Run an embedding request attributed to an organization", - "category": "models", - "subcategory": "inference", - "parameters": [ - { - "in": "query", - "required": false, - "name": "api-version", - "description": "

The API version to use. Optional, but required for some features.

", - "schema": { - "type": "string" - }, - "example": "2024-05-01-preview" - }, - { - "in": "path", - "name": "org", - "required": true, - "description": "

The organization login associated with the organization to which the request is to be attributed.

", - "schema": { - "type": "string" - } - } - ], - "bodyParameters": [ - { - "type": "string", - "name": "model", - "in": "body", - "description": "

ID of the specific model to use for the request. The model ID should be in the format of {publisher}/{model_name} where \"openai/text-embedding-3-small\" is an example of a model ID. You can find supported models in the catalog/models endpoint.

", - "isRequired": true - }, - { - "type": "string or array", - "name": "input", - "in": "body", - "description": "

Input text to embed, encoded as a string or array of strings. To embed multiple inputs in a single request, pass an array of strings. Each input must not exceed the max input tokens for the model, cannot be an empty string, and any array must be 2048 dimensions or less.

", - "isRequired": true - }, - { - "type": "string", - "name": "encoding_format", - "in": "body", - "description": "

The format to return the embeddings in. Can be either float or base64.

", - "enum": [ - "float", - "base64" - ], - "default": "float" - }, - { - "type": "integer", - "name": "dimensions", - "in": "body", - "description": "

The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.

" - }, - { - "type": "string", - "name": "user", - "in": "body", - "description": "

A unique identifier representing your end-user, which can help us to monitor and detect abuse.

" - } - ], - "codeExamples": [ - { - "key": "default", - "request": { - "contentType": "application/json", - "description": "Example", - "acceptHeader": "application/vnd.github.v3+json", - "bodyParameters": { - "model": "openai/text-embedding-3-small", - "input": [ - "The food was delicious and the waiter was very friendly.", - "I had a great time at the restaurant." - ] - }, - "parameters": { - "org": "ORG" - } - }, - "response": { - "statusCode": "200", - "contentType": "application/json", - "description": "", - "example": { - "object": "list", - "data": [ - { - "object": "embedding", - "index": 0, - "embedding": [ - 0.0023064255, - -0.009327292, - -0.0028842222 - ] - } - ], - "model": "openai/text-embedding-3-small", - "usage": { - "prompt_tokens": 8, - "total_tokens": 8 - } - }, - "schema": { - "title": "Embedding Response", - "description": "The response for an embedding request.", - "type": "object", - "properties": { - "object": { - "description": "The object type, which is always \"list\" for embedding responses.", - "type": "string", - "enum": [ - "list" - ] - }, - "data": { - "description": "A list of embedding objects.", - "type": "array", - "items": { - "title": "Embedding Object", - "description": "An embedding vector returned by the model.", - "type": "object", - "properties": { - "object": { - "description": "The object type, which is always \"embedding\".", - "type": "string", - "enum": [ - "embedding" - ] - }, - "index": { - "description": "The index of the embedding in the list of embeddings.", - "type": "integer" - }, - "embedding": { - "description": "The embedding vector, which is a list of floats.", - "type": "array", - "items": { - "type": "number" - } - } - }, - "required": [ - "object", - "index", - "embedding" - ] - } - }, - "model": { - "description": "The model used for the embedding.", - "type": "string" - }, - "usage": { - "description": "Usage statistics for the request.", - "type": "object", - "properties": { - "prompt_tokens": { - "description": "The number of tokens in the input.", - "type": "integer" - }, - "total_tokens": { - "description": "The total number of tokens processed.", - "type": "integer" - } - }, - "required": [ - "prompt_tokens", - "total_tokens" - ] - } - }, - "required": [ - "object", - "data", - "model", - "usage" - ] - } - } - } - ], - "previews": [], - "descriptionHTML": "

This endpoint allows you to run an embedding request attributed to a specific organization. You must be a member of the organization and have enabled models to use this endpoint.\nThe token used to authenticate must have the models: read permission if using a fine-grained PAT or GitHub App minted token.\nThe request body should contain the model ID and the input text(s) for the embedding request. The response will include the generated embeddings.

", - "statusCodes": [ - { - "httpStatusCode": "200", - "description": "

OK

" - } - ] - }, - { - "serverUrl": "https://models.github.ai", - "verb": "post", - "requestPath": "/inference/embeddings", - "title": "Run an embedding request", - "category": "models", - "subcategory": "inference", - "parameters": [ - { - "in": "query", - "required": false, - "name": "api-version", - "description": "

The API version to use. Optional, but required for some features.

", - "schema": { - "type": "string" - }, - "example": "2024-05-01-preview" - } - ], - "bodyParameters": [ - { - "type": "string", - "name": "model", - "in": "body", - "description": "

ID of the specific model to use for the request. The model ID should be in the format of {publisher}/{model_name} where \"openai/text-embedding-3-small\" is an example of a model ID. You can find supported models in the catalog/models endpoint.

", - "isRequired": true - }, - { - "type": "string or array", - "name": "input", - "in": "body", - "description": "

Input text to embed, encoded as a string or array of strings. To embed multiple inputs in a single request, pass an array of strings. Each input must not exceed the max input tokens for the model, cannot be an empty string, and any array must be 2048 dimensions or less.

", - "isRequired": true - }, - { - "type": "string", - "name": "encoding_format", - "in": "body", - "description": "

The format to return the embeddings in. Can be either float or base64.

", - "enum": [ - "float", - "base64" - ], - "default": "float" - }, - { - "type": "integer", - "name": "dimensions", - "in": "body", - "description": "

The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.

" - }, - { - "type": "string", - "name": "user", - "in": "body", - "description": "

A unique identifier representing your end-user, which can help us to monitor and detect abuse.

" - } - ], - "codeExamples": [ - { - "key": "default", - "request": { - "contentType": "application/json", - "description": "Example", - "acceptHeader": "application/vnd.github.v3+json", - "bodyParameters": { - "model": "openai/text-embedding-3-small", - "input": [ - "The food was delicious and the waiter was very friendly.", - "I had a great time at the restaurant." - ] - } - }, - "response": { - "statusCode": "200", - "contentType": "application/json", - "description": "", - "example": { - "object": "list", - "data": [ - { - "object": "embedding", - "index": 0, - "embedding": [ - 0.0023064255, - -0.009327292, - -0.0028842222 - ] - } - ], - "model": "openai/text-embedding-3-small", - "usage": { - "prompt_tokens": 8, - "total_tokens": 8 - } - }, - "schema": { - "title": "Embedding Response", - "description": "The response for an embedding request.", - "type": "object", - "properties": { - "object": { - "description": "The object type, which is always \"list\" for embedding responses.", - "type": "string", - "enum": [ - "list" - ] - }, - "data": { - "description": "A list of embedding objects.", - "type": "array", - "items": { - "title": "Embedding Object", - "description": "An embedding vector returned by the model.", - "type": "object", - "properties": { - "object": { - "description": "The object type, which is always \"embedding\".", - "type": "string", - "enum": [ - "embedding" - ] - }, - "index": { - "description": "The index of the embedding in the list of embeddings.", - "type": "integer" - }, - "embedding": { - "description": "The embedding vector, which is a list of floats.", - "type": "array", - "items": { - "type": "number" - } - } - }, - "required": [ - "object", - "index", - "embedding" - ] - } - }, - "model": { - "description": "The model used for the embedding.", - "type": "string" - }, - "usage": { - "description": "Usage statistics for the request.", - "type": "object", - "properties": { - "prompt_tokens": { - "description": "The number of tokens in the input.", - "type": "integer" - }, - "total_tokens": { - "description": "The total number of tokens processed.", - "type": "integer" - } - }, - "required": [ - "prompt_tokens", - "total_tokens" - ] - } - }, - "required": [ - "object", - "data", - "model", - "usage" - ] - } - } - } - ], - "previews": [], - "descriptionHTML": "

This endpoint allows you to run an embedding request. The token used to authenticate must have the models: read permission if using a fine-grained PAT or GitHub App minted token.\nThe request body should contain the model ID and the input text(s) for the embedding request. The response will include the generated embeddings.

", - "statusCodes": [ - { - "httpStatusCode": "200", - "description": "

OK

" - } - ] } ] }, diff --git a/src/rest/data/ghec-2022-11-28/schema.json b/src/rest/data/ghec-2022-11-28/schema.json index d89b85e54dd4..ff41e428b1e0 100644 --- a/src/rest/data/ghec-2022-11-28/schema.json +++ b/src/rest/data/ghec-2022-11-28/schema.json @@ -181665,6 +181665,10 @@ "httpStatusCode": "409", "description": "

Response if there is already a validation run in progress with a different default setup configuration

" }, + { + "httpStatusCode": "422", + "description": "

Response if the configuration change cannot be made because the repository is not in the required state

" + }, { "httpStatusCode": "503", "description": "

Service unavailable

" @@ -188519,7 +188523,7 @@ "type": "array of integers", "name": "selected_repository_ids", "in": "body", - "description": "

An array of repository IDs to detach from configurations.

" + "description": "

An array of repository IDs to detach from configurations. Up to 1000 IDs can be provided.

" } ], "progAccess": { @@ -284416,6 +284420,116 @@ } ] }, + { + "serverUrl": "https://api.github.com", + "verb": "post", + "requestPath": "/enterprises/{enterprise}/settings/billing/cost-centers", + "title": "Create a new cost center", + "category": "enterprise-admin", + "subcategory": "billing", + "parameters": [ + { + "name": "enterprise", + "description": "

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "bodyParameters": [ + { + "type": "string", + "name": "name", + "in": "body", + "description": "

The name of the cost center (max length 255 characters)

", + "isRequired": true + } + ], + "progAccess": { + "userToServerRest": false, + "serverToServer": false, + "fineGrainedPat": false, + "permissions": [] + }, + "codeExamples": [ + { + "key": "example-1", + "request": { + "contentType": "application/json", + "description": "Example request to create a cost center", + "acceptHeader": "application/vnd.github.v3+json", + "bodyParameters": { + "name": "Engineering Team" + }, + "parameters": { + "enterprise": "ENTERPRISE" + } + }, + "response": { + "statusCode": "200", + "contentType": "application/json", + "description": "

Example response for a created cost center

", + "example": { + "id": "abc123", + "name": "Engineering Team", + "resources": [] + }, + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the cost center" + }, + "name": { + "type": "string", + "description": "Name of the cost center" + }, + "resources": { + "type": "array", + "description": "List of resources assigned to this cost center", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Type of resource (User, Org, or Repo)" + }, + "name": { + "type": "string", + "description": "Name/login of the resource" + } + } + } + } + } + } + } + } + ], + "previews": [], + "descriptionHTML": "

Creates a new cost center for an enterprise. The authenticated user must be an enterprise admin.

", + "statusCodes": [ + { + "httpStatusCode": "200", + "description": "

Cost center created successfully

" + }, + { + "httpStatusCode": "400", + "description": "

Bad request

" + }, + { + "httpStatusCode": "409", + "description": "

Conflict

" + }, + { + "httpStatusCode": "500", + "description": "

Internal server error

" + } + ] + }, { "serverUrl": "https://api.github.com", "verb": "get", @@ -284819,7 +284933,7 @@ "serverUrl": "https://api.github.com", "verb": "post", "requestPath": "/enterprises/{enterprise}/settings/billing/cost-centers/{cost_center_id}/resource", - "title": "Add users to a cost center", + "title": "Add resources to a cost center", "category": "enterprise-admin", "subcategory": "billing", "parameters": [ @@ -284848,6 +284962,18 @@ "name": "users", "in": "body", "description": "

The usernames of the users to add to the cost center.

" + }, + { + "type": "array of strings", + "name": "organizations", + "in": "body", + "description": "

The organizations to add to the cost center.

" + }, + { + "type": "array of strings", + "name": "repositories", + "in": "body", + "description": "

The repositories to add to the cost center.

" } ], "progAccess": { @@ -284892,7 +285018,7 @@ } ], "previews": [], - "descriptionHTML": "

Adds users to a cost center.

\n

The usage for the users will be charged to the cost center's budget. The authenticated user must be an enterprise admin in order to use this endpoint.

", + "descriptionHTML": "

Adds resources to a cost center.

\n

The usage for the resources will be charged to the cost center's budget. The authenticated user must be an enterprise admin in order to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", @@ -284924,7 +285050,7 @@ "serverUrl": "https://api.github.com", "verb": "delete", "requestPath": "/enterprises/{enterprise}/settings/billing/cost-centers/{cost_center_id}/resource", - "title": "Remove users from a cost center", + "title": "Remove resources from a cost center", "category": "enterprise-admin", "subcategory": "billing", "parameters": [ @@ -284953,6 +285079,18 @@ "name": "users", "in": "body", "description": "

The usernames of the users to remove from the cost center.

" + }, + { + "type": "array of strings", + "name": "organizations", + "in": "body", + "description": "

The organizations to remove from the cost center.

" + }, + { + "type": "array of strings", + "name": "repositories", + "in": "body", + "description": "

The repositories to remove from the cost center.

" } ], "progAccess": { @@ -284997,7 +285135,7 @@ } ], "previews": [], - "descriptionHTML": "

Remove users from a cost center.

\n

The usage for the users will no longer be charged to the cost center's budget. The authenticated user must be an enterprise admin in order to use this endpoint.

", + "descriptionHTML": "

Remove resources from a cost center.

\n

The usage for the resources will no longer be charged to the cost center's budget. The authenticated user must be an enterprise admin in order to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", diff --git a/src/rest/data/ghes-3.13-2022-11-28/schema.json b/src/rest/data/ghes-3.13-2022-11-28/schema.json index ace655d3198f..865569b5fef2 100644 --- a/src/rest/data/ghes-3.13-2022-11-28/schema.json +++ b/src/rest/data/ghes-3.13-2022-11-28/schema.json @@ -1846,13 +1846,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the GitHub Actions caches for a repository.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the GitHub Actions caches for a repository.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -2836,13 +2836,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the organizations that are selected to have GitHub Actions enabled in an enterprise. To use this endpoint, the enterprise permission policy for enabled_organizations must be configured to selected. For more information, see \"Set GitHub Actions permissions for an enterprise.\"

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the organizations that are selected to have GitHub Actions enabled in an enterprise. To use this endpoint, the enterprise permission policy for enabled_organizations must be configured to selected. For more information, see \"Set GitHub Actions permissions for an enterprise.\"

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -3503,13 +3503,13 @@ } ], "previews": [], - "descriptionHTML": "

Sets the GitHub Actions permissions policy for repositories and allowed actions in an organization.

\n

If the organization belongs to an enterprise that has set restrictive permissions at the enterprise level, such as allowed_actions to selected actions, then you cannot override them for the organization.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Sets the GitHub Actions permissions policy for repositories and allowed actions in an organization.

\n

If the organization belongs to an enterprise that has set restrictive permissions at the enterprise level, such as allowed_actions to selected actions, then you cannot override them for the organization.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -4668,13 +4668,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories must be configured to selected. For more information, see \"Set GitHub Actions permissions for an organization.\"

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories must be configured to selected. For more information, see \"Set GitHub Actions permissions for an organization.\"

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -4737,13 +4737,13 @@ } ], "previews": [], - "descriptionHTML": "

Replaces the list of selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories must be configured to selected. For more information, see \"Set GitHub Actions permissions for an organization.\"

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Replaces the list of selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories must be configured to selected. For more information, see \"Set GitHub Actions permissions for an organization.\"

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -5112,13 +5112,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the default workflow permissions granted to the GITHUB_TOKEN when running workflows in an organization,\nas well as whether GitHub Actions can submit approving pull request reviews. For more information, see\n\"Setting the permissions of the GITHUB_TOKEN for your organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets the default workflow permissions granted to the GITHUB_TOKEN when running workflows in an organization,\nas well as whether GitHub Actions can submit approving pull request reviews. For more information, see\n\"Setting the permissions of the GITHUB_TOKEN for your organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -7636,7 +7636,6 @@ } ], "previews": [], - "descriptionHTML": "

Adds a repository to an organization secret when the visibility for\nrepository access is set to selected. For more information about setting the visibility, see Create or\nupdate an organization secret.

\n

Authenticated users must have collaborator access to a repository to create, update, or read secrets.

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", @@ -7646,7 +7645,8 @@ "httpStatusCode": "409", "description": "

Conflict when visibility type is not set to selected

" } - ] + ], + "descriptionHTML": "

Adds a repository to an organization secret when the visibility for\nrepository access is set to selected. For more information about setting the visibility, see Create or\nupdate an organization secret.

\n

Authenticated users must have collaborator access to a repository to create, update, or read secrets.

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -10210,13 +10210,13 @@ } ], "previews": [], - "descriptionHTML": "

Removes an organization from the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see \"Create a self-hosted runner group for an enterprise.\"

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Removes an organization from the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see \"Create a self-hosted runner group for an enterprise.\"

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -11398,13 +11398,13 @@ } ], "previews": [], - "descriptionHTML": "

Updates the name and visibility of a self-hosted runner group in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Updates the name and visibility of a self-hosted runner group in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -12618,13 +12618,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the repositories with access to a self-hosted runner group configured in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the repositories with access to a self-hosted runner group configured in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -12772,13 +12772,13 @@ } ], "previews": [], - "descriptionHTML": "

Adds a repository to the list of repositories that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see \"Create a self-hosted runner group for an organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Adds a repository to the list of repositories that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see \"Create a self-hosted runner group for an organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -22404,13 +22404,13 @@ } ], "previews": [], - "descriptionHTML": "

Returns a token that you can pass to the config script. The token expires after one hour.

\n

For example, you can replace TOKEN in the following example with the registration token provided by this endpoint to configure your self-hosted runner:

\n
./config.sh --url https://github.com/octo-org --token TOKEN\n
\n

Authenticated users must have admin access to the repository to use this endpoint.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "

Returns a token that you can pass to the config script. The token expires after one hour.

\n

For example, you can replace TOKEN in the following example with the registration token provided by this endpoint to configure your self-hosted runner:

\n
./config.sh --url https://github.com/octo-org --token TOKEN\n
\n

Authenticated users must have admin access to the repository to use this endpoint.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -28105,13 +28105,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a specific job in a workflow run.

\n

Anyone with read access to the repository can use this endpoint.

\n

If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a specific job in a workflow run.

\n

Anyone with read access to the repository can use this endpoint.

\n

If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -29355,7 +29355,6 @@ } ], "previews": [], - "descriptionHTML": "

Re-run a job and its dependent jobs in a workflow run.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "201", @@ -29365,7 +29364,8 @@ "httpStatusCode": "403", "description": "

Forbidden

" } - ] + ], + "descriptionHTML": "

Re-run a job and its dependent jobs in a workflow run.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -35402,13 +35402,13 @@ } ], "previews": [], - "descriptionHTML": "

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -38165,13 +38165,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a specific workflow run attempt.

\n

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a specific workflow run attempt.

\n

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -43686,13 +43686,13 @@ } ], "previews": [], - "descriptionHTML": "

Disables a workflow and sets the state of the workflow to disabled_manually. You can replace workflow_id with the workflow file name. For example, you could use main.yaml.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Disables a workflow and sets the state of the workflow to disabled_manually. You can replace workflow_id with the workflow file name. For example, you could use main.yaml.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -78406,13 +78406,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the feeds available to the authenticated user. The response provides a URL for each feed. You can then get a specific feed by sending a request to one of the feed URLs.

\n
    \n
  • Timeline: The GitHub Enterprise Server global public timeline
    • \n
  • User: The public timeline for any user, using uri_template. For more information, see \"Hypermedia.\"
    • \n
  • Current user public: The public timeline for the authenticated user
    • \n
  • Current user: The private timeline for the authenticated user
    • \n
  • Current user actor: The private timeline for activity created by the authenticated user
    • \n
  • Current user organizations: The private timeline for the organizations the authenticated user is a member of.
    • \n
  • Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub Enterprise Server.
    • \n
\n

By default, timeline resources are returned in JSON. You can specify the application/atom+xml type in the Accept header to return timeline resources in Atom format. For more information, see \"Media types.\"

\n

Note

\n

\nPrivate feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.

\n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the feeds available to the authenticated user. The response provides a URL for each feed. You can then get a specific feed by sending a request to one of the feed URLs.

\n
    \n
  • Timeline: The GitHub Enterprise Server global public timeline
    • \n
  • User: The public timeline for any user, using uri_template. For more information, see \"Hypermedia.\"
    • \n
  • Current user public: The public timeline for the authenticated user
    • \n
  • Current user: The private timeline for the authenticated user
    • \n
  • Current user actor: The private timeline for activity created by the authenticated user
    • \n
  • Current user organizations: The private timeline for the organizations the authenticated user is a member of.
    • \n
  • Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub Enterprise Server.
    • \n
\n

By default, timeline resources are returned in JSON. You can specify the application/atom+xml type in the Accept header to return timeline resources in Atom format. For more information, see \"Media types.\"

\n

Note

\n

\nPrivate feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.

\n
" } ], "notifications": [ @@ -99842,13 +99842,13 @@ } ], "previews": [], - "descriptionHTML": "

Enables an authenticated GitHub App to find the organization's installation information.

\n

You must use a JWT to access this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Enables an authenticated GitHub App to find the organization's installation information.

\n

You must use a JWT to access this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -131740,7 +131740,6 @@ } ], "previews": [], - "descriptionHTML": "

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

\n

Lists the teams who have push access to this branch. The list includes child teams.

", "statusCodes": [ { "httpStatusCode": "200", @@ -131750,7 +131749,8 @@ "httpStatusCode": "404", "description": "

Resource not found

" } - ] + ], + "descriptionHTML": "

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

\n

Lists the teams who have push access to this branch. The list includes child teams.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -149905,13 +149905,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a single check suite using its id.

\n

Note

\n

\nThe Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

\n
\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a single check suite using its id.

\n

Note

\n

\nThe Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

\n
\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -158952,6 +158952,10 @@ "httpStatusCode": "409", "description": "

Response if there is already a validation run in progress with a different default setup configuration

" }, + { + "httpStatusCode": "422", + "description": "

Response if the configuration change cannot be made because the repository is not in the required state

" + }, { "httpStatusCode": "503", "description": "

Service unavailable

" @@ -185924,13 +185928,13 @@ } ], "previews": [], - "descriptionHTML": "

Deletes a secret in an organization using the secret name.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deletes a secret in an organization using the secret name.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -186908,13 +186912,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists all repositories that have been selected when the visibility\nfor repository access to a secret is set to selected.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists all repositories that have been selected when the visibility\nfor repository access to a secret is set to selected.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -201073,13 +201077,13 @@ } ], "previews": [], - "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -202108,13 +202112,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the audit log for an enterprise.

\n

The authenticated user must be an enterprise admin to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets the audit log for an enterprise.

\n

The authenticated user must be an enterprise admin to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

" } ], "billing": [ @@ -202305,13 +202309,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the GitHub Advanced Security active committers for an enterprise per repository.

\n

Each distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of active_users for each repository.

\n

The total number of repositories with committer information is tracked by the total_count field.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

Success

" } - ] + ], + "descriptionHTML": "

Gets the GitHub Advanced Security active committers for an enterprise per repository.

\n

Each distinct user login across all repositories is counted as a single Advanced Security seat, so the total_advanced_security_committers is not the sum of active_users for each repository.

\n

The total number of repositories with committer information is tracked by the total_count field.

" } ], "code-security-and-analysis": [ @@ -205025,7 +205029,6 @@ } ], "previews": [], - "descriptionHTML": "

When you boot and set up a GitHub instance for the first time, you can use this endpoint to upload a license and set the initial root site administrator password.

\n

Important

\n

\nTo start the configuration process and apply the license, you need to POST to /manage/v1/config/apply

\n
\n

The root site administrator password provided when calling this endpoint is used to authenticate for all other endpoints in the GHES Manage API and the Management Console UI.

\n

Note

\n

\nThe request body for this operation must be submitted as multipart/form-data data. You can can reference the license file by prefixing the filename with the @ symbol using curl. For more information, see the curl documentation.

\n
", "statusCodes": [ { "httpStatusCode": "202", @@ -205043,7 +205046,8 @@ "httpStatusCode": "500", "description": "

Internal error

" } - ] + ], + "descriptionHTML": "

When you boot and set up a GitHub instance for the first time, you can use this endpoint to upload a license and set the initial root site administrator password.

\n

Important

\n

\nTo start the configuration process and apply the license, you need to POST to /manage/v1/config/apply

\n
\n

The root site administrator password provided when calling this endpoint is used to authenticate for all other endpoints in the GHES Manage API and the Management Console UI.

\n

Note

\n

\nThe request body for this operation must be submitted as multipart/form-data data. You can can reference the license file by prefixing the filename with the @ symbol using curl. For more information, see the curl documentation.

\n
" }, { "serverUrl": "http(s)://HOSTNAME", @@ -220802,7 +220806,6 @@ } ], "previews": [], - "descriptionHTML": "

Lists the authenticated user's gists or if called anonymously, this endpoint returns all public gists:

", "statusCodes": [ { "httpStatusCode": "200", @@ -220816,7 +220819,8 @@ "httpStatusCode": "403", "description": "

Forbidden

" } - ] + ], + "descriptionHTML": "

Lists the authenticated user's gists or if called anonymously, this endpoint returns all public gists:

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -268966,13 +268970,13 @@ } ], "previews": [], - "descriptionHTML": "

You can use the REST API to delete comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

You can use the REST API to delete comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -293135,13 +293139,13 @@ } ], "previews": [], - "descriptionHTML": "

Updates a label using the given label name.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Updates a label using the given label name.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -293401,13 +293405,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists labels for issues in a milestone.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists labels for issues in a milestone.

" } ], "milestones": [ @@ -338485,13 +338489,13 @@ } ], "previews": [], - "descriptionHTML": "

Warning

\n

\nClosing down notice: This operation is closing down and will be removed in the future. Use the \"List custom repository roles\" endpoint instead.

\n
\n

List the custom repository roles available in this organization. For more information on custom repository roles, see \"About custom repository roles.\"

\n

The authenticated user must be administrator of the organization or of a repository of the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

Response - list of custom role names

" } - ] + ], + "descriptionHTML": "

Warning

\n

\nClosing down notice: This operation is closing down and will be removed in the future. Use the \"List custom repository roles\" endpoint instead.

\n
\n

List the custom repository roles available in this organization. For more information on custom repository roles, see \"About custom repository roles.\"

\n

The authenticated user must be administrator of the organization or of a repository of the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -355659,13 +355663,13 @@ } ], "previews": [], - "descriptionHTML": "

Updates the webhook configuration for an organization. To update more information about the webhook, including the active state and events, use \"Update an organization webhook .\"

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Updates the webhook configuration for an organization. To update more information about the webhook, including the active state and events, use \"Update an organization webhook .\"

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -356359,7 +356363,6 @@ } ], "previews": [], - "descriptionHTML": "

This will trigger a ping event\nto be sent to the hook.

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

", "statusCodes": [ { "httpStatusCode": "204", @@ -356369,7 +356372,8 @@ "httpStatusCode": "404", "description": "

Resource not found

" } - ] + ], + "descriptionHTML": "

This will trigger a ping event\nto be sent to the hook.

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

" } ] }, @@ -360728,13 +360732,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a specific package version in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the read:packages scope to use this endpoint. For more information, see \"About permissions for GitHub Packages.\"

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a specific package version in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the read:packages scope to use this endpoint. For more information, see \"About permissions for GitHub Packages.\"

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -370346,7 +370350,6 @@ } ], "previews": [], - "descriptionHTML": "

Gets information about a GitHub Enterprise Server Pages site.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", @@ -370356,7 +370359,8 @@ "httpStatusCode": "404", "description": "

Resource not found

" } - ] + ], + "descriptionHTML": "

Gets information about a GitHub Enterprise Server Pages site.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -384029,7 +384033,6 @@ } ], "previews": [], - "descriptionHTML": "

Lists pull requests in a specified repository.

\n

Draft pull requests are available in public repositories with GitHub\nFree and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing\nplans, and in public and private repositories with GitHub Team and GitHub Enterprise\nCloud. For more information, see GitHub's products\nin the GitHub Help documentation.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
", "statusCodes": [ { "httpStatusCode": "200", @@ -384043,7 +384046,8 @@ "httpStatusCode": "422", "description": "

Validation failed, or the endpoint has been spammed.

" } - ] + ], + "descriptionHTML": "

Lists pull requests in a specified repository.

\n

Draft pull requests are available in public repositories with GitHub\nFree and GitHub Free for organizations, GitHub Pro, and legacy per-repository billing\nplans, and in public and private repositories with GitHub Team and GitHub Enterprise\nCloud. For more information, see GitHub's products\nin the GitHub Help documentation.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -399673,13 +399677,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists a maximum of 250 commits for a pull request. To receive a complete\ncommit list for pull requests with more than 250 commits, use the List commits\nendpoint.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists a maximum of 250 commits for a pull request. To receive a complete\ncommit list for pull requests with more than 250 commits, use the List commits\nendpoint.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -403012,13 +403016,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists all review comments for a specified pull request. By default, review comments\nare in ascending order by ID.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github-commitcomment.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github-commitcomment.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github-commitcomment.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github-commitcomment.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists all review comments for a specified pull request. By default, review comments\nare in ascending order by ID.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github-commitcomment.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github-commitcomment.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github-commitcomment.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github-commitcomment.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -425141,7 +425145,6 @@ } ], "previews": [], - "descriptionHTML": "

Create a reaction to a pull request review comment. A response with an HTTP 200 status means that you already added the reaction type to this pull request review comment.

", "statusCodes": [ { "httpStatusCode": "200", @@ -425155,7 +425158,8 @@ "httpStatusCode": "422", "description": "

Validation failed, or the endpoint has been spammed.

" } - ] + ], + "descriptionHTML": "

Create a reaction to a pull request review comment. A response with an HTTP 200 status means that you already added the reaction type to this pull request review comment.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -435182,13 +435186,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists repositories for the specified organization.

\n

Note

\n

\nIn order to see the security_and_analysis block for a repository you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see \"Managing security managers in your organization.\"

\n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists repositories for the specified organization.

\n

Note

\n

\nIn order to see the security_and_analysis block for a repository you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see \"Managing security managers in your organization.\"

\n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -465824,13 +465828,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets all autolinks that are configured for a repository.

\n

Information about autolinks are only available to repository administrators.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets all autolinks that are configured for a repository.

\n

Information about autolinks are only available to repository administrators.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -476124,13 +476128,13 @@ } ], "previews": [], - "descriptionHTML": "

Disables Git LFS for a repository.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Disables Git LFS for a repository.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

" } ], "rule-suites": [ @@ -520041,13 +520045,13 @@ } ], "previews": [], - "descriptionHTML": "

Delete a discussion from a team's page.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}.

\n
\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Delete a discussion from a team's page.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}.

\n
\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -522535,13 +522539,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists a connection between a team and an external group.

\n

You can manage team membership with your identity provider using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see \"GitHub's products\" in the GitHub Help documentation.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists a connection between a team and an external group.

\n

You can manage team membership with your identity provider using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see \"GitHub's products\" in the GitHub Help documentation.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -523420,7 +523424,6 @@ } ], "previews": [], - "descriptionHTML": "

To remove a membership between a user and a team, the authenticated user must have 'admin' permissions to the team or be an owner of the organization that the team is associated with. Removing team membership does not delete the user, it just removes their membership from the team.

\n

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

\n

Note

\n

\nWhen you have team synchronization set up for a team with your organization's identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team's membership. If you have access to manage group membership in your IdP, you can manage GitHub Enterprise Server team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see \"Synchronizing teams between your identity provider and GitHub Enterprise Server.\"

\n
\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}/memberships/{username}.

\n
", "statusCodes": [ { "httpStatusCode": "204", @@ -523430,7 +523433,8 @@ "httpStatusCode": "403", "description": "

Forbidden if team synchronization is set up

" } - ] + ], + "descriptionHTML": "

To remove a membership between a user and a team, the authenticated user must have 'admin' permissions to the team or be an owner of the organization that the team is associated with. Removing team membership does not delete the user, it just removes their membership from the team.

\n

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

\n

Note

\n

\nWhen you have team synchronization set up for a team with your organization's identity provider (IdP), you will see an error if you attempt to use the API for making changes to the team's membership. If you have access to manage group membership in your IdP, you can manage GitHub Enterprise Server team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see \"Synchronizing teams between your identity provider and GitHub Enterprise Server.\"

\n
\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}/memberships/{username}.

\n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -533717,13 +533721,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the SSH signing keys for a user. This operation is accessible by anyone.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the SSH signing keys for a user. This operation is accessible by anyone.

" } ] } diff --git a/src/rest/data/ghes-3.14-2022-11-28/schema.json b/src/rest/data/ghes-3.14-2022-11-28/schema.json index ebd9ccbfe7eb..b3721d9a921c 100644 --- a/src/rest/data/ghes-3.14-2022-11-28/schema.json +++ b/src/rest/data/ghes-3.14-2022-11-28/schema.json @@ -1152,13 +1152,13 @@ } ], "previews": [], - "descriptionHTML": "

Sets the GitHub Actions cache usage policy for an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Sets the GitHub Actions cache usage policy for an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -8117,13 +8117,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets your public key, which you need to encrypt secrets. You need to\nencrypt a secret before you can create or update secrets.

\n

Anyone with read access to the repository can use this endpoint.

\n

If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets your public key, which you need to encrypt secrets. You need to\nencrypt a secret before you can create or update secrets.

\n

Anyone with read access to the repository can use this endpoint.

\n

If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -13243,13 +13243,13 @@ } ], "previews": [], - "descriptionHTML": "

Adds a self-hosted runner to a runner group configured in an organization.

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Adds a self-hosted runner to a runner group configured in an organization.

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -23668,13 +23668,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a specific self-hosted runner configured in a repository.

\n

Authenticated users must have admin access to the repository to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a specific self-hosted runner configured in a repository.

\n

Authenticated users must have admin access to the repository to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -26737,13 +26737,13 @@ } ], "previews": [], - "descriptionHTML": "

Creates a repository variable that you can reference in a GitHub Actions workflow.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "

Creates a repository variable that you can reference in a GitHub Actions workflow.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -74261,13 +74261,13 @@ } ], "previews": [], - "descriptionHTML": "

These are events that you've received by watching repositories and following users. If you are authenticated as the\ngiven user, you will see private events. Otherwise, you'll only see public events.

\n

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

These are events that you've received by watching repositories and following users. If you are authenticated as the\ngiven user, you will see private events. Otherwise, you'll only see public events.

\n

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -78061,13 +78061,13 @@ } ], "previews": [], - "descriptionHTML": "

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
" } ], "feeds": [ @@ -78406,13 +78406,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the feeds available to the authenticated user. The response provides a URL for each feed. You can then get a specific feed by sending a request to one of the feed URLs.

\n
    \n
  • Timeline: The GitHub Enterprise Server global public timeline
    • \n
  • User: The public timeline for any user, using uri_template. For more information, see \"Hypermedia.\"
    • \n
  • Current user public: The public timeline for the authenticated user
    • \n
  • Current user: The private timeline for the authenticated user
    • \n
  • Current user actor: The private timeline for activity created by the authenticated user
    • \n
  • Current user organizations: The private timeline for the organizations the authenticated user is a member of.
    • \n
  • Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub Enterprise Server.
    • \n
\n

By default, timeline resources are returned in JSON. You can specify the application/atom+xml type in the Accept header to return timeline resources in Atom format. For more information, see \"Media types.\"

\n

Note

\n

\nPrivate feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.

\n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the feeds available to the authenticated user. The response provides a URL for each feed. You can then get a specific feed by sending a request to one of the feed URLs.

\n
    \n
  • Timeline: The GitHub Enterprise Server global public timeline
    • \n
  • User: The public timeline for any user, using uri_template. For more information, see \"Hypermedia.\"
    • \n
  • Current user public: The public timeline for the authenticated user
    • \n
  • Current user: The private timeline for the authenticated user
    • \n
  • Current user actor: The private timeline for activity created by the authenticated user
    • \n
  • Current user organizations: The private timeline for the organizations the authenticated user is a member of.
    • \n
  • Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub Enterprise Server.
    • \n
\n

By default, timeline resources are returned in JSON. You can specify the application/atom+xml type in the Accept header to return timeline resources in Atom format. For more information, see \"Media types.\"

\n

Note

\n

\nPrivate feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.

\n
" } ], "notifications": [ @@ -94548,7 +94548,6 @@ } ], "previews": [], - "descriptionHTML": "

Uninstalls a GitHub App on a user, organization, or enterprise account. If you prefer to temporarily suspend an app's access to your account's resources, then we recommend the \"Suspend an app installation\" endpoint.

\n

You must use a JWT to access this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", @@ -94558,7 +94557,8 @@ "httpStatusCode": "404", "description": "

Resource not found

" } - ] + ], + "descriptionHTML": "

Uninstalls a GitHub App on a user, organization, or enterprise account. If you prefer to temporarily suspend an app's access to your account's resources, then we recommend the \"Suspend an app installation\" endpoint.

\n

You must use a JWT to access this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -138160,13 +138160,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a single check run using its id.

\n

Note

\n

\nThe Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

\n
\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a single check run using its id.

\n

Note

\n

\nThe Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array.

\n
\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -158952,6 +158952,10 @@ "httpStatusCode": "409", "description": "

Response if there is already a validation run in progress with a different default setup configuration

" }, + { + "httpStatusCode": "422", + "description": "

Response if the configuration change cannot be made because the repository is not in the required state

" + }, { "httpStatusCode": "503", "description": "

Service unavailable

" @@ -201378,13 +201382,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the statistics about security products for a GitHub Enterprise Server instance.

\n

To use this endpoint, you must be a site admin.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets the statistics about security products for a GitHub Enterprise Server instance.

\n

To use this endpoint, you must be a site admin.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -201639,13 +201643,13 @@ } ], "previews": [], - "descriptionHTML": "

Sets the message and expiration time for the global announcement banner in your enterprise.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Sets the message and expiration time for the global announcement banner in your enterprise.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -206918,7 +206922,6 @@ } ], "previews": [], - "descriptionHTML": "

Check your installation's maintenance status:

", "statusCodes": [ { "httpStatusCode": "200", @@ -206928,7 +206931,8 @@ "httpStatusCode": "401", "description": "

Unauthorized

" } - ] + ], + "descriptionHTML": "

Check your installation's maintenance status:

" }, { "serverUrl": "http(s)://HOSTNAME", @@ -425588,7 +425592,6 @@ } ], "previews": [], - "descriptionHTML": "

List the reactions to an issue comment.

", "statusCodes": [ { "httpStatusCode": "200", @@ -425598,7 +425601,8 @@ "httpStatusCode": "404", "description": "

Resource not found

" } - ] + ], + "descriptionHTML": "

List the reactions to an issue comment.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -468955,13 +468959,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists public repositories for the specified user.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists public repositories for the specified user.

" } ], "autolinks": [ @@ -489322,13 +489326,13 @@ } ], "previews": [], - "descriptionHTML": "

Updates the webhook configuration for a repository. To update more information about the webhook, including the active state and events, use \"Update a repository webhook.\"

\n

OAuth app tokens and personal access tokens (classic) need the write:repo_hook or repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Updates the webhook configuration for a repository. To update more information about the webhook, including the active state and events, use \"Update a repository webhook.\"

\n

OAuth app tokens and personal access tokens (classic) need the write:repo_hook or repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -517022,13 +517026,13 @@ } ], "previews": [], - "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Remove a repository from a team endpoint.

\n
\n

If the authenticated user is an organization owner or a team maintainer, they can remove any repositories from the team. To remove a repository from a team as an organization member, the authenticated user must have admin access to the repository and must be able to see the team. NOTE: This does not delete the repository, it just removes it from the team.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Remove a repository from a team endpoint.

\n
\n

If the authenticated user is an organization owner or a team maintainer, they can remove any repositories from the team. To remove a repository from a team as an organization member, the authenticated user must have admin access to the repository and must be able to see the team. NOTE: This does not delete the repository, it just removes it from the team.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", diff --git a/src/rest/data/ghes-3.15-2022-11-28/schema.json b/src/rest/data/ghes-3.15-2022-11-28/schema.json index d350ea04602a..e76a3fc28f5a 100644 --- a/src/rest/data/ghes-3.15-2022-11-28/schema.json +++ b/src/rest/data/ghes-3.15-2022-11-28/schema.json @@ -159644,6 +159644,10 @@ "httpStatusCode": "409", "description": "

Response if there is already a validation run in progress with a different default setup configuration

" }, + { + "httpStatusCode": "422", + "description": "

Response if the configuration change cannot be made because the repository is not in the required state

" + }, { "httpStatusCode": "503", "description": "

Service unavailable

" diff --git a/src/rest/data/ghes-3.16-2022-11-28/schema.json b/src/rest/data/ghes-3.16-2022-11-28/schema.json index 322de7bd9b64..b7c26aa74e18 100644 --- a/src/rest/data/ghes-3.16-2022-11-28/schema.json +++ b/src/rest/data/ghes-3.16-2022-11-28/schema.json @@ -553,13 +553,13 @@ } ], "previews": [], - "descriptionHTML": "

Deletes an artifact for a workflow run.\nOAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deletes an artifact for a workflow run.\nOAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -2168,13 +2168,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the customization template for an OpenID Connect (OIDC) subject claim.

\n

OAuth app tokens and personal access tokens (classic) need the read:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

A JSON serialized template for OIDC subject claim customization

" } - ] + ], + "descriptionHTML": "

Gets the customization template for an OpenID Connect (OIDC) subject claim.

\n

OAuth app tokens and personal access tokens (classic) need the read:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -4867,13 +4867,13 @@ } ], "previews": [], - "descriptionHTML": "

Removes a repository from the list of selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories must be configured to selected. For more information, see \"Set GitHub Actions permissions for an organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Removes a repository from the list of selected repositories that are enabled for GitHub Actions in an organization. To use this endpoint, the organization permission policy for enabled_repositories must be configured to selected. For more information, see \"Set GitHub Actions permissions for an organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -5375,13 +5375,13 @@ } ], "previews": [], - "descriptionHTML": "

Sets the GitHub Actions permissions policy for enabling GitHub Actions and allowed actions in the repository.

\n

If the repository belongs to an organization or enterprise that has set restrictive permissions at the organization or enterprise levels, such as allowed_actions to selected actions, then you cannot override them for the repository.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Sets the GitHub Actions permissions policy for enabling GitHub Actions and allowed actions in the repository.

\n

If the repository belongs to an organization or enterprise that has set restrictive permissions at the organization or enterprise levels, such as allowed_actions to selected actions, then you cannot override them for the repository.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -9432,13 +9432,13 @@ } ], "previews": [], - "descriptionHTML": "

Creates a new self-hosted runner group for an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "

Creates a new self-hosted runner group for an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -24719,13 +24719,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists all organization variables.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists all organization variables.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -25062,13 +25062,13 @@ } ], "previews": [], - "descriptionHTML": "

Updates an organization variable that you can reference in a GitHub Actions workflow.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Updates an organization variable that you can reference in a GitHub Actions workflow.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -29296,13 +29296,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists jobs for a workflow run. You can use parameters to narrow the list of results. For more information\nabout using parameters, see Parameters.

\n

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists jobs for a workflow run. You can use parameters to narrow the list of results. For more information\nabout using parameters, see Parameters.

\n

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

" } ], "workflow-runs": [ @@ -35486,13 +35486,13 @@ } ], "previews": [], - "descriptionHTML": "

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -66882,13 +66882,13 @@ } ], "previews": [], - "descriptionHTML": "

This is the user's organization dashboard. You must be authenticated as the user to view this.

\n

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

This is the user's organization dashboard. You must be authenticated as the user to view this.

\n

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -159879,6 +159879,10 @@ "httpStatusCode": "409", "description": "

Response if there is already a validation run in progress with a different default setup configuration

" }, + { + "httpStatusCode": "422", + "description": "

Response if the configuration change cannot be made because the repository is not in the required state

" + }, { "httpStatusCode": "503", "description": "

Service unavailable

" @@ -193560,13 +193564,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists all secrets available in an organization without revealing their\nencrypted values.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists all secrets available in an organization without revealing their\nencrypted values.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -193967,13 +193971,13 @@ } ], "previews": [], - "descriptionHTML": "

Deletes a secret in an organization using the secret name.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deletes a secret in an organization using the secret name.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -196822,13 +196826,13 @@ } ], "previews": [], - "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -197198,13 +197202,13 @@ } ], "previews": [], - "descriptionHTML": "

Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.

" } ] }, @@ -203703,13 +203707,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets all custom deployment protection rule integrations that are available for an environment.

\n

The authenticated user must have admin or owner permissions to the repository to use this endpoint.

\n

For more information about environments, see \"Using environments for deployment.\"

\n

For more information about the app that is providing this custom deployment rule, see \"GET an app\".

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

A list of custom deployment rule integrations available for this environment.

" } - ] + ], + "descriptionHTML": "

Gets all custom deployment protection rule integrations that are available for an environment.

\n

The authenticated user must have admin or owner permissions to the repository to use this endpoint.

\n

For more information about environments, see \"Using environments for deployment.\"

\n

For more information about the app that is providing this custom deployment rule, see \"GET an app\".

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -212339,13 +212343,13 @@ } ], "previews": [], - "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -225991,13 +225995,13 @@ } ], "previews": [], - "descriptionHTML": "

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

\n

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send \"octo_cat\" as the login, a user named \"octo-cat\" will be created.

\n

If the login name or email address is already associated with an account, the server will return a 422 response.

", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

\n

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send \"octo_cat\" as the login, a user named \"octo-cat\" will be created.

\n

If the login name or email address is already associated with an account, the server will return a 422 response.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -320965,7 +320969,6 @@ } ], "previews": [], - "descriptionHTML": "

Lists the most commonly used licenses on GitHub. For more information, see \"Licensing a repository .\"

", "statusCodes": [ { "httpStatusCode": "200", @@ -320975,7 +320978,8 @@ "httpStatusCode": "304", "description": "

Not modified

" } - ] + ], + "descriptionHTML": "

Lists the most commonly used licenses on GitHub. For more information, see \"Licensing a repository .\"

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -353343,13 +353347,13 @@ } ], "previews": [], - "descriptionHTML": "

Remove an organization role from a user. For more information on organization roles, see \"Using organization roles.\"

\n

The authenticated user must be an administrator for the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Remove an organization role from a user. For more information on organization roles, see \"Using organization roles.\"

\n

The authenticated user must be an administrator for the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -354150,13 +354154,13 @@ } ], "previews": [], - "descriptionHTML": "

Deletes a custom organization role. For more information on custom organization roles, see \"Managing people's access to your organization with roles.\"

\n

To use this endpoint, the authenticated user must be one of:

\n
    \n
  • An administrator for the organization.
    • \n
  • A user, or a user on a team, with the fine-grained permissions of write_organization_custom_org_role in the organization.
    • \n
\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deletes a custom organization role. For more information on custom organization roles, see \"Managing people's access to your organization with roles.\"

\n

To use this endpoint, the authenticated user must be one of:

\n
    \n
  • An administrator for the organization.
    • \n
  • A user, or a user on a team, with the fine-grained permissions of write_organization_custom_org_role in the organization.
    • \n
\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -355178,13 +355182,13 @@ } ], "previews": [], - "descriptionHTML": "

List all users who are outside collaborators of an organization.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

List all users who are outside collaborators of an organization.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -367944,13 +367948,13 @@ } ], "previews": [], - "descriptionHTML": "

Returns the webhook configuration for an organization. To get more information about the webhook, including the active state and events, use \"Get an organization webhook .\"

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Returns the webhook configuration for an organization. To get more information about the webhook, including the active state and events, use \"Get an organization webhook .\"

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -382405,13 +382409,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a specific package version for a public package owned by a specified user.

\n

OAuth app tokens and personal access tokens (classic) need the read:packages scope to use this endpoint. For more information, see \"About permissions for GitHub Packages.\"

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a specific package version for a public package owned by a specified user.

\n

OAuth app tokens and personal access tokens (classic) need the read:packages scope to use this endpoint. For more information, see \"About permissions for GitHub Packages.\"

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -384186,13 +384190,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets information about the single most recent build of a GitHub Enterprise Server Pages site.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets information about the single most recent build of a GitHub Enterprise Server Pages site.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -466087,13 +466091,13 @@ } ], "previews": [], - "descriptionHTML": "

Enables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see \"About security alerts for vulnerable dependencies\".

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Enables dependency alerts and the dependency graph for a repository. The authenticated user must have admin access to the repository. For more information, see \"About security alerts for vulnerable dependencies\".

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -499778,13 +499782,13 @@ } ], "previews": [], - "descriptionHTML": "

Returns the webhook configuration for a repository. To get more information about the webhook, including the active state and events, use \"Get a repository webhook.\"

\n

OAuth app tokens and personal access tokens (classic) need the read:repo_hook or repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Returns the webhook configuration for a repository. To get more information about the webhook, including the active state and events, use \"Get a repository webhook.\"

\n

OAuth app tokens and personal access tokens (classic) need the read:repo_hook or repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -533111,13 +533115,13 @@ } ], "previews": [], - "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Create a discussion comment endpoint.

\n
\n

Creates a new comment on a team discussion.

\n

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see \"Rate limits for the API\" and \"Best practices for using the REST API.\"

\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Create a discussion comment endpoint.

\n
\n

Creates a new comment on a team discussion.

\n

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see \"Rate limits for the API\" and \"Best practices for using the REST API.\"

\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -533983,13 +533987,13 @@ } ], "previews": [], - "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Update a discussion comment endpoint.

\n
\n

Edits the body text of a discussion comment.

\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Update a discussion comment endpoint.

\n
\n

Edits the body text of a discussion comment.

\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -535050,13 +535054,13 @@ } ], "previews": [], - "descriptionHTML": "

Creates a new discussion post on a team's page.

\n

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see \"Rate limits for the API\" and \"Best practices for using the REST API.\"

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route POST /organizations/{org_id}/team/{team_id}/discussions.

\n
\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "

Creates a new discussion post on a team's page.

\n

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see \"Rate limits for the API\" and \"Best practices for using the REST API.\"

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route POST /organizations/{org_id}/team/{team_id}/discussions.

\n
\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -538871,13 +538875,13 @@ } ], "previews": [], - "descriptionHTML": "

Deletes a connection between a team and an external group.

\n

You can manage team membership with your IdP using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deletes a connection between a team and an external group.

\n

You can manage team membership with your IdP using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

" } ], "members": [ diff --git a/src/rest/data/ghes-3.17-2022-11-28/schema.json b/src/rest/data/ghes-3.17-2022-11-28/schema.json index cc1be67d28d0..153c9529ccac 100644 --- a/src/rest/data/ghes-3.17-2022-11-28/schema.json +++ b/src/rest/data/ghes-3.17-2022-11-28/schema.json @@ -264,13 +264,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists all artifacts for a repository.

\n

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists all artifacts for a repository.

\n

Anyone with read access to the repository can use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -1000,13 +1000,13 @@ } ], "previews": [], + "descriptionHTML": "

Gets the total GitHub Actions cache usage for an enterprise.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.

\n

OAuth tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "

Gets the total GitHub Actions cache usage for an enterprise.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.

\n

OAuth tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -1228,13 +1228,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the total GitHub Actions cache usage for an organization.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.

\n

OAuth tokens and personal access tokens (classic) need the read:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets the total GitHub Actions cache usage for an organization.\nThe data fetched using this API is refreshed approximately every 5 minutes, so values returned from this endpoint may take at least 5 minutes to get updated.

\n

OAuth tokens and personal access tokens (classic) need the read:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -1554,13 +1554,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets GitHub Actions cache usage policy for a repository.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets GitHub Actions cache usage policy for a repository.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -2555,13 +2555,13 @@ } ], "previews": [], + "descriptionHTML": "

Gets the GitHub Actions permissions policy for organizations and allowed actions in an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "

Gets the GitHub Actions permissions policy for organizations and allowed actions in an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -5636,13 +5636,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the settings for selected actions that are allowed in a repository. To use this endpoint, the repository policy for allowed_actions must be configured to selected. For more information, see \"Set GitHub Actions permissions for a repository.\"

\n

You must authenticate using an access token with the repo scope to use this endpoint. GitHub Apps must have the administration repository permission to use this API.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets the settings for selected actions that are allowed in a repository. To use this endpoint, the repository policy for allowed_actions must be configured to selected. For more information, see \"Set GitHub Actions permissions for a repository.\"

\n

You must authenticate using an access token with the repo scope to use this endpoint. GitHub Apps must have the administration repository permission to use this API.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -6431,6 +6431,7 @@ } ], "previews": [], + "descriptionHTML": "

Creates or updates an organization secret with an encrypted value. Encrypt your secret using\nLibSodium. For more information, see \"Encrypting secrets for the REST API.\"

\n

Authenticated users must have collaborator access to a repository to create, update, or read secrets.

\n

OAuth tokens and personal access tokens (classic) need theadmin:org scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "201", @@ -6440,8 +6441,7 @@ "httpStatusCode": "204", "description": "

Response when updating a secret

" } - ], - "descriptionHTML": "

Creates or updates an organization secret with an encrypted value. Encrypt your secret using\nLibSodium. For more information, see \"Encrypting secrets for the REST API.\"

\n

Authenticated users must have collaborator access to a repository to create, update, or read secrets.

\n

OAuth tokens and personal access tokens (classic) need theadmin:org scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -7507,13 +7507,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists all repositories that have been selected when the visibility\nfor repository access to a secret is set to selected.

\n

Authenticated users must have collaborator access to a repository to create, update, or read secrets.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists all repositories that have been selected when the visibility\nfor repository access to a secret is set to selected.

\n

Authenticated users must have collaborator access to a repository to create, update, or read secrets.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -10618,13 +10618,13 @@ } ], "previews": [], + "descriptionHTML": "

Adds a self-hosted runner to a runner group configured in an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ], - "descriptionHTML": "

Adds a self-hosted runner to a runner group configured in an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -10688,13 +10688,13 @@ } ], "previews": [], + "descriptionHTML": "

Removes a self-hosted runner from a group configured in an enterprise. The runner is then returned to the default group.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ], - "descriptionHTML": "

Removes a self-hosted runner from a group configured in an enterprise. The runner is then returned to the default group.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -12820,13 +12820,13 @@ } ], "previews": [], + "descriptionHTML": "

Adds a repository to the list of repositories that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see \"Create a self-hosted runner group for an organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ], - "descriptionHTML": "

Adds a repository to the list of repositories that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see \"Create a self-hosted runner group for an organization.\"

\n

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -13217,13 +13217,13 @@ } ], "previews": [], - "descriptionHTML": "

Replaces the list of self-hosted runners that are part of an organization runner group.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Replaces the list of self-hosted runners that are part of an organization runner group.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -13365,13 +13365,13 @@ } ], "previews": [], + "descriptionHTML": "

Removes a self-hosted runner from a group configured in an organization. The runner is then returned to the default group.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ], - "descriptionHTML": "

Removes a self-hosted runner from a group configured in an organization. The runner is then returned to the default group.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" + ] } ], "self-hosted-runners": [ @@ -16258,13 +16258,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets a specific self-hosted runner configured in an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets a specific self-hosted runner configured in an enterprise.

\n

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -17269,13 +17269,13 @@ } ], "previews": [], + "descriptionHTML": "

Lists all self-hosted runners configured in an organization.

\n

Authenticated users must have admin access to the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "

Lists all self-hosted runners configured in an organization.

\n

Authenticated users must have admin access to the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -26158,6 +26158,7 @@ } ], "previews": [], + "descriptionHTML": "

Lists all repositories that can access an organization variable\nthat is available to selected repositories.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

", "statusCodes": [ { "httpStatusCode": "200", @@ -26167,8 +26168,7 @@ "httpStatusCode": "409", "description": "

Response when the visibility of the variable is not set to selected

" } - ], - "descriptionHTML": "

Lists all repositories that can access an organization variable\nthat is available to selected repositories.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -27265,13 +27265,13 @@ } ], "previews": [], + "descriptionHTML": "

Lists all environment variables.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "

Lists all environment variables.

\n

Authenticated users must have collaborator access to a repository to create, update, or read variables.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -35197,13 +35197,13 @@ } ], "previews": [], - "descriptionHTML": "

Deletes a specific workflow run.

\n

Anyone with write access to the repository can use this endpoint.

\n

If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deletes a specific workflow run.

\n

Anyone with write access to the repository can use this endpoint.

\n

If the repository is private, OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -38549,7 +38549,6 @@ } ], "previews": [], - "descriptionHTML": "

Cancels a workflow run using its id.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "202", @@ -38559,7 +38558,8 @@ "httpStatusCode": "409", "description": "

Conflict

" } - ] + ], + "descriptionHTML": "

Cancels a workflow run using its id.

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -44059,13 +44059,13 @@ } ], "previews": [], - "descriptionHTML": "

You can use this endpoint to manually trigger a GitHub Actions workflow run. You can replace workflow_id with the workflow file name. For example, you could use main.yaml.

\n

You must configure your GitHub Actions workflow to run when the workflow_dispatch webhook event occurs. The inputs are configured in the workflow file. For more information about how to configure the workflow_dispatch event in the workflow file, see \"Events that trigger workflows.\"

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

You can use this endpoint to manually trigger a GitHub Actions workflow run. You can replace workflow_id with the workflow file name. For example, you could use main.yaml.

\n

You must configure your GitHub Actions workflow to run when the workflow_dispatch webhook event occurs. The inputs are configured in the workflow file. For more information about how to configure the workflow_dispatch event in the workflow file, see \"Events that trigger workflows.\"

\n

OAuth tokens and personal access tokens (classic) need the repo scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -59388,13 +59388,13 @@ } ], "previews": [], - "descriptionHTML": "

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Note

\n

\nThis API is not built to serve real-time use cases. Depending on the time of day, event latency can be anywhere from 30s to 6h.

\n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -103901,13 +103901,13 @@ } ], "previews": [], + "descriptionHTML": "

Revokes the installation token you're using to authenticate as an installation and access this endpoint.

\n

Once an installation token is revoked, the token is invalidated and cannot be used. Other endpoints that require the revoked installation token must have a new installation token to work. You can create a new token using the \"Create an installation access token for an app\" endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ], - "descriptionHTML": "

Revokes the installation token you're using to authenticate as an installation and access this endpoint.

\n

Once an installation token is revoked, the token is invalidated and cannot be used. Other endpoints that require the revoked installation token must have a new installation token to work. You can create a new token using the \"Create an installation access token for an app\" endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -108746,13 +108746,13 @@ } ], "previews": [], - "descriptionHTML": "

Returns the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see \"Creating a GitHub App.\"

\n

You must use a JWT to access this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Returns the webhook configuration for a GitHub App. For more information about configuring a webhook for your app, see \"Creating a GitHub App.\"

\n

You must use a JWT to access this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -160174,6 +160174,10 @@ "httpStatusCode": "409", "description": "

Response if there is already a validation run in progress with a different default setup configuration

" }, + { + "httpStatusCode": "422", + "description": "

Response if the configuration change cannot be made because the repository is not in the required state

" + }, { "httpStatusCode": "503", "description": "

Service unavailable

" @@ -167315,6 +167319,7 @@ } ], "previews": [], + "descriptionHTML": "

Lists the repositories associated with a code security configuration in an organization.

\n

The authenticated user must be an administrator or security manager for the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the write:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", @@ -167328,8 +167333,7 @@ "httpStatusCode": "404", "description": "

Resource not found

" } - ], - "descriptionHTML": "

Lists the repositories associated with a code security configuration in an organization.

\n

The authenticated user must be an administrator or security manager for the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the write:org scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -184173,7 +184177,6 @@ } ], "previews": [], - "descriptionHTML": "

Updates the contents of a specified commit comment.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github-commitcomment.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github-commitcomment.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github-commitcomment.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github-commitcomment.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
", "statusCodes": [ { "httpStatusCode": "200", @@ -184183,7 +184186,8 @@ "httpStatusCode": "404", "description": "

Resource not found

" } - ] + ], + "descriptionHTML": "

Updates the contents of a specified commit comment.

\n

This endpoint supports the following custom media types. For more information, see \"Media types.\"

\n
    \n
  • application/vnd.github-commitcomment.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
    • \n
  • application/vnd.github-commitcomment.text+json: Returns a text only representation of the markdown body. Response will include body_text.
    • \n
  • application/vnd.github-commitcomment.html+json: Returns HTML rendered from the body's markdown. Response will include body_html.
    • \n
  • application/vnd.github-commitcomment.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.
    • \n
" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -195736,13 +195740,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists all repositories that have been selected when the visibility\nfor repository access to a secret is set to selected.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists all repositories that have been selected when the visibility\nfor repository access to a secret is set to selected.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -204134,13 +204138,13 @@ } ], "previews": [], + "descriptionHTML": "

Gets all custom deployment protection rules that are enabled for an environment. Anyone with read access to the repository can use this endpoint. For more information about environments, see \"Using environments for deployment.\"

\n

For more information about the app that is providing this custom deployment rule, see the documentation for the GET /apps/{app_slug} endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

List of deployment protection rules

" } - ], - "descriptionHTML": "

Gets all custom deployment protection rules that are enabled for an environment. Anyone with read access to the repository can use this endpoint. For more information about environments, see \"Using environments for deployment.\"

\n

For more information about the app that is providing this custom deployment rule, see the documentation for the GET /apps/{app_slug} endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -209690,13 +209694,13 @@ } ], "previews": [], + "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -209753,13 +209757,13 @@ } ], "previews": [], + "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -210146,13 +210150,13 @@ } ], "previews": [], + "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -210331,13 +210335,13 @@ } ], "previews": [], + "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "" + ] } ], "announcement": [ @@ -210418,13 +210422,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the current message and expiration date of the global announcement banner in your enterprise.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets the current message and expiration date of the global announcement banner in your enterprise.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -212291,13 +212295,13 @@ } ], "previews": [], + "descriptionHTML": "

Deletes an existing audit log stream configuration for an enterprise.

\n

When using this endpoint, you must encrypt the credentials following the same encryption steps as outlined in the guide on encrypting secrets. See \"Encrypting secrets for the REST API.\"

", "statusCodes": [ { "httpStatusCode": "204", "description": "

The audit log stream configuration was deleted successfully.

" } - ], - "descriptionHTML": "

Deletes an existing audit log stream configuration for an enterprise.

\n

When using this endpoint, you must encrypt the credentials following the same encryption steps as outlined in the guide on encrypting secrets. See \"Encrypting secrets for the REST API.\"

" + ] } ], "billing": [ @@ -213667,13 +213671,13 @@ } ], "previews": [], - "descriptionHTML": "

Updates the distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Create a team endpoint to create a team with LDAP mapping.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Updates the distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Create a team endpoint to create a team with LDAP mapping.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -214247,13 +214251,13 @@ } ], "previews": [], - "descriptionHTML": "

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ] + ], + "descriptionHTML": "

Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201 is returned, the sync job is queued successfully, and is performed when the instance is ready.

" } ], "license": [ @@ -214332,13 +214336,13 @@ } ], "previews": [], - "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "" } ], "manage-ghes": [ @@ -217164,13 +217168,13 @@ } ], "previews": [], - "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -217546,13 +217550,13 @@ } ], "previews": [], + "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "201", "description": "

Created

" } - ], - "descriptionHTML": "" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -218409,13 +218413,13 @@ } ], "previews": [], - "descriptionHTML": "

In addition to seeing the download status at the \"Get a pre-receive environment\" endpoint, there is also this separate endpoint for just the download status.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

In addition to seeing the download status at the \"Get a pre-receive environment\" endpoint, there is also this separate endpoint for just the download status.

" } ], "pre-receive-hooks": [ @@ -218621,13 +218625,13 @@ } ], "previews": [], + "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -219719,13 +219723,13 @@ } ], "previews": [], + "descriptionHTML": "

Deletes any overridden enforcement on this repository for the specified hook.

\n

Responds with effective values inherited from owner and/or global level.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

Responds with effective values inherited from owner and/or global level.

" } - ], - "descriptionHTML": "

Deletes any overridden enforcement on this repository for the specified hook.

\n

Responds with effective values inherited from owner and/or global level.

" + ] } ], "scim": [ @@ -325395,13 +325399,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the most recent migrations, including both exports (which can be started through the REST API) and imports (which cannot be started using the REST API).

\n

A list of repositories is only returned for export migrations.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the most recent migrations, including both exports (which can be started through the REST API) and imports (which cannot be started using the REST API).

\n

A list of repositories is only returned for export migrations.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -342613,6 +342617,7 @@ } ], "previews": [], + "descriptionHTML": "

Warning

\n

\nClosing down notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n
\n

If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see \"Working with two-factor authentication.\"

\n

You can only send one of these scope keys at a time.

", "statusCodes": [ { "httpStatusCode": "200", @@ -342622,8 +342627,7 @@ "httpStatusCode": "422", "description": "

Validation failed, or the endpoint has been spammed.

" } - ], - "descriptionHTML": "

Warning

\n

\nClosing down notice: GitHub Enterprise Server will discontinue the OAuth Authorizations API, which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our web application flow. The OAuth Authorizations API will be removed on November 13, 2020. For more information, including scheduled brownouts, see the blog post.

\n
\n

If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see \"Working with two-factor authentication.\"

\n

You can only send one of these scope keys at a time.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -350098,13 +350102,13 @@ } ], "previews": [], - "descriptionHTML": "

Lists the fine-grained permissions that can be used in custom repository roles for an organization. For more information, see \"About custom repository roles.\"

\n

The authenticated user must be an administrator of the organization or of a repository of the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Lists the fine-grained permissions that can be used in custom repository roles for an organization. For more information, see \"About custom repository roles.\"

\n

The authenticated user must be an administrator of the organization or of a repository of the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org or repo scope to use this endpoint.

" } ], "members": [ @@ -354726,13 +354730,13 @@ } ], "previews": [], - "descriptionHTML": "

Remove an organization role from a user. For more information on organization roles, see \"Using organization roles.\"

\n

The authenticated user must be an administrator for the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Remove an organization role from a user. For more information on organization roles, see \"Using organization roles.\"

\n

The authenticated user must be an administrator for the organization to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -355533,13 +355537,13 @@ } ], "previews": [], - "descriptionHTML": "

Deletes a custom organization role. For more information on custom organization roles, see \"Managing people's access to your organization with roles.\"

\n

To use this endpoint, the authenticated user must be one of:

\n
    \n
  • An administrator for the organization.
    • \n
  • A user, or a user on a team, with the fine-grained permissions of write_organization_custom_org_role in the organization.
    • \n
\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ] + ], + "descriptionHTML": "

Deletes a custom organization role. For more information on custom organization roles, see \"Managing people's access to your organization with roles.\"

\n

To use this endpoint, the authenticated user must be one of:

\n
    \n
  • An administrator for the organization.
    • \n
  • A user, or a user on a team, with the fine-grained permissions of write_organization_custom_org_role in the organization.
    • \n
\n

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -356737,7 +356741,6 @@ } ], "previews": [], - "descriptionHTML": "

Removing a user from this list will remove them from all the organization's repositories.

", "statusCodes": [ { "httpStatusCode": "204", @@ -356747,7 +356750,8 @@ "httpStatusCode": "422", "description": "

Unprocessable Entity if user is a member of the organization

" } - ] + ], + "descriptionHTML": "

Removing a user from this list will remove them from all the organization's repositories.

" } ], "personal-access-tokens": [ @@ -370299,13 +370303,13 @@ } ], "previews": [], - "descriptionHTML": "

Updates the webhook configuration for an organization. To update more information about the webhook, including the active state and events, use \"Update an organization webhook .\"

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Updates the webhook configuration for an organization. To update more information about the webhook, including the active state and events, use \"Update an organization webhook .\"

\n

You must be an organization owner to use this endpoint.

\n

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit\nwebhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -375440,13 +375444,13 @@ } ], "previews": [], + "descriptionHTML": "

Gets a specific package version in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the read:packages scope to use this endpoint. For more information, see \"About permissions for GitHub Packages.\"

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "

Gets a specific package version in an organization.

\n

OAuth app tokens and personal access tokens (classic) need the read:packages scope to use this endpoint. For more information, see \"About permissions for GitHub Packages.\"

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -420387,13 +420391,13 @@ } ], "previews": [], - "descriptionHTML": "

Gets the users or teams whose review is requested for a pull request. Once a requested reviewer submits a review, they are no longer considered a requested reviewer. Their review will instead be returned by the List reviews for a pull request operation.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Gets the users or teams whose review is requested for a pull request. Once a requested reviewer submits a review, they are no longer considered a requested reviewer. Their review will instead be returned by the List reviews for a pull request operation.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -434563,13 +434567,13 @@ } ], "previews": [], - "descriptionHTML": "

List the reactions to a team discussion comment.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route GET /organizations/:org_id/team/:team_id/discussions/:discussion_number/comments/:comment_number/reactions.

\n
\n

OAuth app tokens and personal access tokens (classic) need the read:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

List the reactions to a team discussion comment.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route GET /organizations/:org_id/team/:team_id/discussions/:discussion_number/comments/:comment_number/reactions.

\n
\n

OAuth app tokens and personal access tokens (classic) need the read:discussion scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -466342,13 +466346,13 @@ } ], "previews": [], + "descriptionHTML": "

Lists languages for the specified repository. The value shown for each language is the number of bytes of code written in that language.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "

Lists languages for the specified repository. The value shown for each language is the number of bytes of code written in that language.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -487847,7 +487851,6 @@ } ], "previews": [], - "descriptionHTML": "", "statusCodes": [ { "httpStatusCode": "200", @@ -487857,7 +487860,8 @@ "httpStatusCode": "400", "description": "

Bad Request

" } - ] + ], + "descriptionHTML": "" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -504251,13 +504255,13 @@ } ], "previews": [], + "descriptionHTML": "

Updates the webhook configuration for a repository. To update more information about the webhook, including the active state and events, use \"Update a repository webhook.\"

\n

OAuth app tokens and personal access tokens (classic) need the write:repo_hook or repo scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ], - "descriptionHTML": "

Updates the webhook configuration for a repository. To update more information about the webhook, including the active state and events, use \"Update a repository webhook.\"

\n

OAuth app tokens and personal access tokens (classic) need the write:repo_hook or repo scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -526076,13 +526080,13 @@ } ], "previews": [], + "descriptionHTML": "

To delete a team, the authenticated user must be an organization owner or team maintainer.

\n

If you are an organization owner, deleting a parent team will delete all of its child teams as well.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}.

\n
", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ], - "descriptionHTML": "

To delete a team, the authenticated user must be an organization owner or team maintainer.

\n

If you are an organization owner, deleting a parent team will delete all of its child teams as well.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}.

\n
" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -538504,13 +538508,13 @@ } ], "previews": [], - "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new List discussion comments endpoint.

\n
\n

List all comments on a team discussion.

\n

OAuth app tokens and personal access tokens (classic) need the read:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new List discussion comments endpoint.

\n
\n

List all comments on a team discussion.

\n

OAuth app tokens and personal access tokens (classic) need the read:discussion scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -541904,13 +541908,13 @@ } ], "previews": [], + "descriptionHTML": "

Delete a discussion from a team's page.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}.

\n
\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "204", "description": "

No Content

" } - ], - "descriptionHTML": "

Delete a discussion from a team's page.

\n

Note

\n

\nYou can also specify a team by org_id and team_id using the route DELETE /organizations/{org_id}/team/{team_id}/discussions/{discussion_number}.

\n
\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

" + ] }, { "serverUrl": "http(s)://HOSTNAME/api/v3", @@ -543821,13 +543825,13 @@ } ], "previews": [], - "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Update a discussion endpoint.

\n
\n

Edits the title and body text of a discussion post. Only the parameters you provide are updated.

\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

", "statusCodes": [ { "httpStatusCode": "200", "description": "

OK

" } - ] + ], + "descriptionHTML": "

Warning

\n

\nEndpoint closing down notice: This endpoint route is closing down and will be removed from the Teams API. We recommend migrating your existing code to use the new Update a discussion endpoint.

\n
\n

Edits the title and body text of a discussion post. Only the parameters you provide are updated.

\n

OAuth app tokens and personal access tokens (classic) need the write:discussion scope to use this endpoint.

" }, { "serverUrl": "http(s)://HOSTNAME/api/v3", diff --git a/src/rest/lib/config.json b/src/rest/lib/config.json index 4cedf55b9415..92ac14a55511 100644 --- a/src/rest/lib/config.json +++ b/src/rest/lib/config.json @@ -47,5 +47,5 @@ ] } }, - "sha": "527d41e4237d9ad0bac93932fe1d2fb22f8d1b97" + "sha": "664cf25da36ebb8f97693e51663addaed26bbae5" } \ No newline at end of file diff --git a/src/search/components/input/AISearchCTAPopup.tsx b/src/search/components/input/AISearchCTAPopup.tsx index 73ad751e7f45..1aeabbe69bb7 100644 --- a/src/search/components/input/AISearchCTAPopup.tsx +++ b/src/search/components/input/AISearchCTAPopup.tsx @@ -5,6 +5,8 @@ import { focusTrap } from '@primer/behaviors' import { useTranslation } from '@/languages/components/useTranslation' import { useMaxWidthBreakpoint, useMinWidthBreakpoint } from '../hooks/useBreakpoint' import { useCTAPopoverContext } from '@/frame/components/context/CTAContext' +import { sendEvent } from '@/events/components/events' +import { EventType } from '@/events/types' let previouslyFocused: HTMLElement | null = null @@ -13,11 +15,13 @@ export function AISearchCTAPopup({ dismiss, setIsSearchOpen, isDismissible = true, + bannerType = 'popover', }: { isOpen: boolean dismiss?: () => void setIsSearchOpen: (value: boolean) => void isDismissible?: boolean + bannerType?: 'popover' | 'footer' }) { const { t } = useTranslation('search') const { permanentDismiss } = useCTAPopoverContext() @@ -26,7 +30,21 @@ export function AISearchCTAPopup({ let overlayRef = useRef(null) let dismissButtonRef = useRef(null) + // Analytics helper functions + const sendCTAAnalytics = (variation: 'dismiss' | 'ask_copilot') => { + const experimentName = + bannerType === 'footer' ? 'copilot_footer_banner' : 'copilot_popover_banner' + sendEvent({ + type: EventType.experiment, + experiment_name: experimentName, + experiment_variation: variation, + experiment_success: true, + }) + } + const openSearch = () => { + // Send analytics before taking action + sendCTAAnalytics('ask_copilot') setIsSearchOpen(true) // They engaged with the CTA, so let's not show this popup for them anymore permanentDismiss() @@ -47,6 +65,8 @@ export function AISearchCTAPopup({ if (isTooSmallForCTA) { return } + // Send analytics before taking action + sendCTAAnalytics('dismiss') if (previouslyFocused) { previouslyFocused.focus() } diff --git a/src/search/lib/ai-search-proxy.ts b/src/search/lib/ai-search-proxy.ts index 7c2384039a1c..599ed87dd03f 100644 --- a/src/search/lib/ai-search-proxy.ts +++ b/src/search/lib/ai-search-proxy.ts @@ -4,6 +4,7 @@ import got from 'got' import { getHmacWithEpoch } from '@/search/lib/helpers/get-cse-copilot-auth' import { getCSECopilotSource } from '@/search/lib/helpers/cse-copilot-docs-versions' import type { ExtendedRequest } from '@/types' +import { handleExternalSearchAnalytics } from '@/search/lib/helpers/external-search-analytics' export const aiSearchProxy = async (req: ExtendedRequest, res: Response) => { const { query, version } = req.body @@ -29,6 +30,15 @@ export const aiSearchProxy = async (req: ExtendedRequest, res: Response) => { return } + // Handle search analytics and client_name validation + const analyticsError = await handleExternalSearchAnalytics(req, 'ai-search') + if (analyticsError) { + res.status(analyticsError.status).json({ + errors: [{ message: analyticsError.error }], + }) + return + } + const diagnosticTags = [ `version:${version}`.slice(0, 200), `language:${req.language}`.slice(0, 200), diff --git a/src/search/lib/helpers/external-search-analytics.ts b/src/search/lib/helpers/external-search-analytics.ts new file mode 100644 index 000000000000..e6e4754d8246 --- /dev/null +++ b/src/search/lib/helpers/external-search-analytics.ts @@ -0,0 +1,95 @@ +import { publish } from '@/events/lib/hydro' +import { hydroNames } from '@/events/lib/schema' + +/** + * Handles search analytics and client_name validation for external requests + * Returns null if the request should continue, or an error response object if validation failed + */ +export async function handleExternalSearchAnalytics( + req: any, + searchContext: string, +): Promise<{ error: string; status: number } | null> { + const host = req.headers['x-host'] || req.headers.host + const normalizedHost = stripPort(host as string) + + // Skip analytics entirely for production and internal staging environments + if ( + normalizedHost === 'docs.github.com' || + normalizedHost.endsWith('.github.net') || + normalizedHost.endsWith('.githubapp.com') + ) { + return null + } + + // For localhost, send analytics but auto-set client_name if not provided + let client_name = req.query.client_name || req.body?.client_name + if (normalizedHost === 'localhost' && !client_name) { + client_name = 'localhost' + } + + // For all other external requests, require explicit client_name + if (!client_name) { + return { + status: 400, + error: "Missing required parameter 'client_name' for external requests", + } + } + + // Send search event with client identifier + try { + await publish({ + schema: hydroNames.search, + value: { + type: 'search', + version: '1.0.0', + context: { + event_id: crypto.randomUUID(), + user: 'server-side', + version: '1.0.0', + created: new Date().toISOString(), + hostname: normalizedHost, + path: '', + search: '', + hash: '', + path_language: 'en', + path_version: '', + path_product: '', + path_article: '', + }, + search_query: 'REDACTED', + search_context: searchContext, + search_client: client_name as string, + }, + }) + } catch (error) { + // Don't fail the request if analytics fails + console.error('Failed to send search analytics:', error) + } + + return null +} + +/** + * Determines if a host should bypass client_name requirement for analytics + * Returns true if the host is docs.github.com or ends with github.net or githubapp.com + * (for production and internal staging environments) + * Note: localhost is NOT included here as it should send analytics with auto-set client_name + */ +export function shouldBypassClientNameRequirement(host: string | undefined): boolean { + if (!host) return false + + const normalizedHost = stripPort(host) + return ( + normalizedHost === 'docs.github.com' || + normalizedHost.endsWith('.github.net') || + normalizedHost.endsWith('.githubapp.com') + ) +} + +/** + * Strips port number from host string + */ +function stripPort(host: string): string { + const [hostname] = host.split(':') + return hostname +} diff --git a/src/search/lib/routes/combined-search-route.ts b/src/search/lib/routes/combined-search-route.ts index 581bf38f25f8..07302f4c6e03 100644 --- a/src/search/lib/routes/combined-search-route.ts +++ b/src/search/lib/routes/combined-search-route.ts @@ -3,6 +3,7 @@ import { getAISearchAutocompleteResults } from '@/search/lib/get-elasticsearch-r import { searchCacheControl } from '@/frame/middleware/cache-control' import { SURROGATE_ENUMS, setFastlySurrogateKey } from '@/frame/middleware/set-fastly-surrogate-key' import { handleGetSearchResultsError } from '@/search/middleware/search-routes' +import { handleExternalSearchAnalytics } from '@/search/lib/helpers/external-search-analytics' import type { Request, Response } from 'express' import type { CombinedSearchResponse, GeneralSearchResponse } from '@/search/types' @@ -35,6 +36,14 @@ export async function combinedSearchRoute(req: Request, res: Response) { return res.status(400).json(combinedValidationErrors[0]) } + // Handle search analytics and client_name validation + const analyticsError = await handleExternalSearchAnalytics(req, 'combined-search') + if (analyticsError) { + return res.status(analyticsError.status).json({ + error: analyticsError.error, + }) + } + try { const autocompletePromise = getAISearchAutocompleteResults({ indexName: aiIndexName, diff --git a/src/search/middleware/search-routes.ts b/src/search/middleware/search-routes.ts index af3af78d12ac..278ef9d0a2c7 100644 --- a/src/search/middleware/search-routes.ts +++ b/src/search/middleware/search-routes.ts @@ -17,6 +17,7 @@ import { getAISearchAutocompleteResults } from '@/search/lib/get-elasticsearch-r import { getSearchFromRequestParams } from '@/search/lib/search-request-params/get-search-from-request-params' import { getGeneralSearchResults } from '@/search/lib/get-elasticsearch-results/general-search' import { combinedSearchRoute } from '@/search/lib/routes/combined-search-route' +import { handleExternalSearchAnalytics } from '@/search/lib/helpers/external-search-analytics' const router = express.Router() @@ -36,6 +37,14 @@ router.get( return res.status(400).json(validationErrors[0]) } + // Handle search analytics and client_name validation + const analyticsError = await handleExternalSearchAnalytics(req, 'general-search') + if (analyticsError) { + return res.status(analyticsError.status).json({ + error: analyticsError.error, + }) + } + const getResultOptions = { indexName, searchParams, diff --git a/src/webhooks/lib/config.json b/src/webhooks/lib/config.json index 59cb003c2a03..410b359640df 100644 --- a/src/webhooks/lib/config.json +++ b/src/webhooks/lib/config.json @@ -1,3 +1,3 @@ { - "sha": "527d41e4237d9ad0bac93932fe1d2fb22f8d1b97" + "sha": "664cf25da36ebb8f97693e51663addaed26bbae5" } \ No newline at end of file