Merge pull request #12066 from github/repo-sync

repo sync

Author: Octomerger

content/graphql/guides/index.md

@@ -18,5 +18,6 @@ children:
   - /using-the-explorer
   - /managing-enterprise-accounts
   - /using-the-graphql-api-for-discussions
+  - /migrating-graphql-global-node-ids
 ---
 

content/graphql/guides/migrating-graphql-global-node-ids.md

@@ -0,0 +1,69 @@
+---
+title: Migrating GraphQL global node IDs
+intro: 'Learn about the two global node ID formats and how to migrate from the legacy format to the new format.'
+versions:
+  fpt: '*'
+  ghec: '*'
+topics:
+  - API
+shortTitle: Migrating global node IDs
+---
+
+## Background
+
+The {% data variables.product.product_name %} GraphQL API currently supports two types of global node ID formats. The legacy format will be deprecated and replaced with a new format.  This guide shows you how to migrate to the new format, if necessary. 
+
+By migrating to the new format, you ensure that the response times of your requests remain consistent and small. You also ensure that your application continues to work once the legacy IDs are fully deprecated.
+
+To learn more about why the legacy global node ID format will be deprecated, see "[New global ID format coming to GraphQL](https://github.blog/2021-02-10-new-global-id-format-coming-to-graphql)."
+
+## Determining if you need to take action
+
+You only need to follow the migration steps if you store references to GraphQL global node IDs.  These IDs correspond to the `id` field for any object in the schema.  If you don't store any global node IDs, then you can continue to interact with the API with no change.
+
+Additionally, if you currently decode the legacy IDs to extract type information (for example, if you use the first two characters of `PR_kwDOAHz1OX4uYAah` to determine if the object is a pull request), your service will break since the format of the IDs has changed.  You should migrate your service to treat these IDs as opaque strings.  These IDs will be unique, therefore you can rely on them directly as references.
+
+
+## Migrating to the new global IDs
+
+To facilitate migration to the new ID format, you can use the `X-Github-Next-Global-ID` header in your GraphQL API requests. The value of the `X-Github-Next-Global-ID` header can be `1` or `0`.  Setting the value to `1` will force the response payload to always use the new ID format for any object that you requested the `id` field for.  Setting the value to `0` will revert to default behavior, which is to show the legacy ID or new ID depending on the object creation date. 
+
+Here is an example request using cURL:
+
+```
+$ curl \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "X-Github-Next-Global-ID: 1" \
+  https://api.github.com/graphql \
+  -d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'
+```
+
+Even though the legacy ID `MDQ6VXNlcjM0MDczMDM=` was used in the query, the response will contain the new ID format:
+```
+{"data":{"node":{"id":"U_kgDOADP9xw"}}}
+```
+With the `X-Github-Next-Global-ID` header, you can find the new ID format for legacy IDs that you reference in your application. You can then update those references with the ID received in the response. You should update all references to legacy IDs and use the new ID format for any subsequent requests to the API. 
+To perform bulk operations, you can use aliases to submit multiple node queries in one API call. For more information, see "[the GraphQL docs](https://graphql.org/learn/queries/#aliases)."
+
+You can also get the new ID for a collection of items. For example, if you wanted to get the new ID for the last 10 repositories in your organization, you could use a query like this:
+```
+{
+  organization(login: "github") {
+    repositories(last: 10) {
+      edges {
+        cursor
+        node {
+          name
+          id
+        }
+      }
+    }
+  }
+}
+```
+
+Note that setting `X-Github-Next-Global-ID` to `1` will affect the return value of every `id` field in your query.  This means that even when you submit a non-`node` query, you will get back the new format ID if you requested the `id` field.
+
+## Sharing feedback
+
+If you have any concerns about the rollout of this change impacting your app, please [contact {% data variables.product.product_name %}](https://support.github.com/contact) and include information such as your app name so that we can better assist you.

translations/es-ES/content/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md

@@ -0,0 +1,101 @@
+---
+title: Using OpenID Connect with reusable workflows
+shortTitle: Using OpenID Connect with reusable workflows
+intro: 'You can use reusable workflows with OIDC to standardize and security harden your deployment steps.'
+miniTocMaxHeadingLevel: 3
+redirect_from:
+  - /actions/deployment/security-hardening-your-deployments/using-oidc-with-your-reusable-workflows
+versions:
+  fpt: '*'
+  ghae: 'issue-4757-and-5856'
+  ghec: '*'
+type: how_to
+topics:
+  - Workflows
+  - Security
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+{% note %}
+
+**Note:** Reusable workflows are currently in beta and subject to change.
+
+{% endnote %}
+
+## About reusable workflows
+
+Rather than copying and pasting deployment jobs from one workflow to another, you can create a reusable workflow that performs the deployment steps. A reusable workflow can be used by another workflow if it meets one of the access requirements described in "[Reusing workflows](/actions/learn-github-actions/reusing-workflows#access-to-reusable-workflows)."
+
+When combined with OpenID Connect (OIDC), reusable workflows let you enforce consistent deployments across your repository, organization, or enterprise. You can do this by defining trust conditions on cloud roles based on reusable workflows.
+
+In order to create trust conditions based on reusable workflows, your cloud provider must support custom claims for `job_workflow_ref`. This allows your cloud provider to identify which repository the job originally came from. If your cloud provider only supports the standard claims (_audience_ and _subject_), it will not be able to determine that the job originated from the reusable workflow repository. Cloud providers that support `job_workflow_ref` include Google Cloud Platform and HashiCorp Vault.
+
+Before proceeding, you should be familiar with the concepts of [reusable workflows](/actions/learn-github-actions/reusing-workflows) and [OpenID Connect](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
+
+## How the token works with reusable workflows
+
+During a workflow run, {% data variables.product.prodname_dotcom %}'s OIDC provider presents a OIDC token to the cloud provider which contains information about the job. If that job is part of a reusable workflow, the token will include the standard claims that contain information about the calling workflow, and will also include a custom claim called `job_workflow_ref` that contains information about the called workflow.
+
+For example, the following OIDC token is for a job that was part of a called workflow. The `workflow`, `ref`, and other attributes describe the caller workflow, while `job_workflow_ref` refers to the called workflow:
+
+```yaml{:copy}
+{
+  "typ": "JWT",
+  "alg": "RS256",
+  "x5t": "example-thumbprint",
+  "kid": "example-key-id"
+}
+{
+  "jti": "example-id",
+  "sub": "repo:octo-org/octo-repo:environment:prod",
+  "aud": "https://github.com/octo-org",
+  "ref": "refs/heads/main",
+  "sha": "example-sha",
+  "repository": "octo-org/octo-repo",
+  "repository_owner": "octo-org",
+  "run_id": "example-run-id",
+  "run_number": "10",
+  "run_attempt": "2",
+  "actor": "octocat",
+  "workflow": "example-workflow",
+  "head_ref": "",
+  "base_ref": "",
+  "event_name": "workflow_dispatch",
+  "ref_type": "branch",
+  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
+  "iss": "https://token.actions.githubusercontent.com",
+  "nbf": 1632492967,
+  "exp": 1632493867,
+  "iat": 1632493567
+}
+```
+
+If your reusable workflow performs deployment steps, then it will typically need access to a specific cloud role, and you might want to allow any repository in your organization to call that reusable workflow. To permit this, you'll create the trust condition that allows any repository and any caller workflow, and then filter on the organization and the called workflow. See the next section for some examples.
+
+## Examples
+
+**Filtering for reusable workflows within a specific repository**
+
+You can configure a custom claim that filters for any reusable workflow in a specific repository. In this example, the workflow run must have originated from a job defined in a reusable workflow in the `octo-org/octo-automation` repository, and in any repository that is owned by the `octo-org` organization.
+
+- **Subject**:
+  - Syntax: `repo:ORG_NAME/*`
+  - Example: `repo:octo-org/*`
+
+- **Custom claim**:
+  - Syntax: `job_workflow_ref:ORG_NAME/REPO_NAME`
+  - Example: `job_workflow_ref:octo-org/octo-automation@*`
+
+**Filtering for a specific reusable workflow at a specific ref**
+
+You can configure a custom claim that filters for a specific reusable workflow. In this example, the workflow run must have originated from a job defined in the reusable workflow `octo-org/octo-automation/.github/workflows/deployment.yml`, and in any repository that is owned by the `octo-org` organization.
+
+- **Subject**:
+  - Syntax: `repo:ORG_NAME/*` 
+  - Example: `repo:octo-org/*` 
+
+- **Custom claim**:
+  - Syntax: `job_workflow_ref:ORG_NAME/REPO_NAME/.github/workflows/WORKFLOW_FILE@ref` 
+  - Example: `job_workflow_ref:octo-org/octo-automation/.github/workflows/deployment.yml@ 10040c56a8c0253d69db7c1f26a0d227275512e2`

translations/es-ES/content/admin/enterprise-management/caching-repositories/about-repository-caching.md

@@ -0,0 +1,21 @@
+---
+title: About repository caching
+intro: "You can increase the performance of Git read operations for distributed teams and CI farms with repository caching."
+versions:
+  ghes: '>=3.3'
+type: overview
+topics:
+  - Enterprise
+---
+
+{% data reusables.enterprise.repository-caching-release-phase %}
+
+If you have teams and CI farms located around the world, you may experience reduced performance on your primary {% data variables.product.prodname_ghe_server %} instance. While active geo-replicas can improve the performance of read requests, this comes at the cost of limiting write throughput. To reduce load on your primary instance and improve write throughput performance, you can configure a repository cache, an asynchronous read-only mirror of repositories located near these geographically-distributed clients. 
+
+A repository cache eliminates the need for {% data variables.product.product_name %} to transmit the same Git data over a long-haul network link multiple times to serve multiple clients, by serving your repository data close to CI farms and distributed teams. For instance, if your primary instance is in North America and you also have a large presence in Asia, you will benefit from setting up the repository cache in Asia for use by CI runners there.
+
+The repository cache listens to the primary instance, whether that's a single instance or a geo-replicated set of instances, for changes to Git data. CI farms and other read-heavy consumers clone and fetch from the repository cache instead of the primary instance. Changes are propagated across the network, at periodic intervals, once per cache instance rather than once per client. Git data will typically be visible on the repository cache within several minutes after the data is pushed to the primary instance.
+
+You have fine-grained control over which repositories are allowed to sync to the repository cache.
+
+{% data reusables.enterprise.repository-caching-config-summary %} For more information, see "[Configuring a repository cache](/admin/enterprise-management/caching-repositories/configuring-a-repository-cache)."

translations/es-ES/content/admin/enterprise-management/caching-repositories/configuring-a-repository-cache.md

@@ -0,0 +1,90 @@
+---
+title: Configuring a repository cache
+intro: "You can configure a repository cache by creating a new appliance, connecting the repository cache to your primary appliance, and configuring replication of repository networks to the repository cache."
+versions:
+  ghes: '>=3.3'
+type: how_to
+topics:
+  - Enterprise
+---
+
+{% data reusables.enterprise.repository-caching-release-phase %}
+
+## About configuration for repository caching
+
+{% data reusables.enterprise.repository-caching-config-summary %} Then, you can set data location policies that govern which repository networks are replicated to the repository cache.
+
+Repository caching is not supported with clustering.
+
+## DNS for repository caches
+
+The primary instance and repository cache should have different DNS names. For example, if your primary instance is at `github.example.com`, you might decide to name a cache `europe-ci.github.example.com` or `github.asia.example.com`.
+
+To have your CI machines fetch from the repository cache instead of the primary instance, you can use Git's `url.<base>.insteadOf` configuration setting. For more information, see [`git-config`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtinsteadOf) in the Git documentation. 
+
+For example, the global `.gitconfig` for the CI machine would include these lines.
+
+```
+[url "https://europe-ci.github.example.com/"]
+	insteadOf = https://github.example.com/
+```
+
+Then, when told to fetch `https://github.example.com/myorg/myrepo`, Git will instead fetch from `https://europe-ci.github.example.com/myorg/myrepo`.
+
+## Configuring a repository cache
+
+1. During the beta, you must enable the feature flag for repository caching on your primary {% data variables.product.prodname_ghe_server %} appliance.
+   
+   ```
+   $ ghe-config cluster.cache-enabled true
+   ```
+
+1. Set up a new {% data variables.product.prodname_ghe_server %} appliance on your desired platform. This appliance will be your repository cache. For more information, see "[Setting up a {% data variables.product.prodname_ghe_server %} instance](/admin/guides/installation/setting-up-a-github-enterprise-server-instance)."
+{% data reusables.enterprise_installation.replica-steps %}
+1. Connect to the repository cache's IP address using SSH.
+
+   ```shell
+   $ ssh -p 122 admin@<em>REPLICA IP</em>
+   ```
+
+{% data reusables.enterprise_installation.generate-replication-key-pair %}
+{% data reusables.enterprise_installation.add-ssh-key-to-primary %}
+1. To verify the connection to the primary and enable replica mode for the repository cache, run `ghe-repl-setup` again.
+
+   ```shell
+   $ ghe-repl-setup <em>PRIMARY IP</em>
+   ```
+
+1. Set a `cache_location` for the repository cache, replacing *CACHE-LOCATION* with an alphanumeric identifier, such as the region where the cache is deployed.
+
+   ```shell
+   $ ghe-repl-node --cache <em>CACHE-LOCATION</em>
+   ```
+
+{% data reusables.enterprise_installation.replication-command %}
+{% data reusables.enterprise_installation.verify-replication-channel %}
+1. To enable replication of repository networks to the repository cache, set a data location policy. For more information, see "[Data location policies](#data-location-policies)."
+
+## Data location policies
+
+You can control data locality by configuring data location policies for your repositories with the `spokesctl cache-policy` command. Data location policies determine which repository networks are replicated on which repository caches. By default, no repository networks will be replicated on any repository caches until a data location policy is configured.
+
+You can configure a policy to replicate all networks with the `--default` flag. For example, this command will create a policy to replicate a single copy of every repository network to the set of repository caches whose `cache_location` is "kansas".
+
+ ```
+ $ ghe-spokesctl cache-policy set --default 1 kansas
+ ```
+
+To configure replication for a repository network, specify the repository that is the root of the network. A repository network includes a repository and all of the repository's forks. You cannot replicate part of a network without replicating the whole network.
+
+```
+$ ghe-spokesctl cache-policy set <owner/repository> 1 kansas
+```
+
+You can override a policy that replicates all networks and exclude specific networks by specifying a replica count of zero for the network. For example, this command specifies that any repository cache in location "kansas" cannot contain any copies of that network.
+
+```
+$ ghe-spokesctl cache-policy set <owner/repository> 0 kansas
+```
+
+Replica counts greater than one in a given cache location are not supported.

translations/es-ES/content/admin/enterprise-management/caching-repositories/index.md

@@ -0,0 +1,13 @@
+---
+title: Caching repositories
+intro: "You can improve performance for your geographically-distributed team with repository caching, which provides read-only mirrors close to your users and CI clients."
+versions:
+  ghes: '>=3.3'
+topics:
+  - Enterprise
+children:
+  - /about-repository-caching
+  - /configuring-a-repository-cache
+---
+
+{% data reusables.enterprise.repository-caching-release-phase %}