Merge branch 'main' into versioning-in-landing-pages

Author: sarahs

assets/images/help/desktop/cherry-picking.png

@@ -42,6 +42,7 @@ includeGuides:
   - /actions/guides/building-and-testing-java-with-maven
   - /actions/guides/building-and-testing-java-with-gradle
   - /actions/guides/building-and-testing-java-with-ant
+  - /actions/guides/installing-an-apple-certificate-on-macos-runners-for-xcode-development
   - /actions/guides/publishing-nodejs-packages
   - /actions/guides/publishing-java-packages-with-maven
   - /actions/guides/publishing-java-packages-with-gradle
@@ -81,6 +82,7 @@ includeGuides:
 <!-- {% link_in_list /building-and-testing-java-with-maven %} -->
 <!-- {% link_in_list /building-and-testing-java-with-gradle %} -->
 <!-- {% link_in_list /building-and-testing-java-with-ant %} -->
+<!-- {% link_in_list /installing-an-apple-certificate-on-macos-runners-for-xcode-development %} -->
 <!-- {% link_in_list /about-packaging-with-github-actions %} -->
 <!-- {% link_in_list /publishing-nodejs-packages %} -->
 <!-- {% link_in_list /publishing-java-packages-with-maven %} -->

content/actions/guides/index.md

@@ -0,0 +1,135 @@
+---
+title: Installing an Apple certificate on macOS runners for Xcode development
+intro: 'You can sign Xcode apps within your continuous integration (CI) workflow by installing an Apple code signing certificate on {% data variables.product.prodname_actions %} runners.'
+product: '{% data reusables.gated-features.actions %}'
+versions:
+  free-pro-team: '*'
+  enterprise-server: '>=2.22'
+  github-ae: '*'
+type: 'tutorial'
+topics:
+  - 'CI'
+  - 'Xcode'
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+{% data reusables.actions.ae-beta %}
+
+### Introduction
+
+This guide shows you how to add a step to your continuous integration (CI) workflow that installs an Apple code signing certificate and provisioning profile on {% data variables.product.prodname_actions %} runners. This will allow you to sign your Xcode apps for publishing to the Apple App Store, or distributing it to test groups.
+
+### Prerequisites
+
+You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see:
+
+- "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)"
+- "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)"
+
+You should have an understanding of Xcode app building and signing. For more information, see the [Apple developer documentation](https://developer.apple.com/documentation/).
+
+### Creating secrets for your certificate and provisioning profile
+
+The signing process involves storing certificates and provisioning profiles, transferring them to the runner, importing them to the runner's keychain, and using them in your build.
+
+To use your certificate and provisioning profile on a runner, we strongly recommend that you use {% data variables.product.prodname_dotcom %} secrets. For more information on creating secrets and using them in a workflow, see "[Encrypted secrets](/actions/reference/encrypted-secrets)."
+
+Create secrets in your repository or organization for the following items:
+
+* Your Apple signing certificate.
+
+  - This is your `p12` certificate file. For more information on exporting your signing certificate from Xcode, see the [Xcode documentation](https://help.apple.com/xcode/mac/current/#/dev154b28f09).
+  
+  - You should convert your certificate to Base64 when saving it as a secret. In this example, the secret is named `BUILD_CERTIFICATE_BASE64`.
+
+  - Use the following command to convert your certificate to Base64 and copy it to your clipboard:
+
+    ```shell
+    base64 <em>build_certificate</em>.p12 | pbcopy
+    ```
+* The password for your Apple signing certificate.
+  - In this example, the secret is named `P12_PASSWORD`.
+
+* Your Apple provisioning profile.
+
+  - For more information on exporting your provisioning profile from Xcode, see the [Xcode documentation](https://help.apple.com/xcode/mac/current/#/deva899b4fe5).
+
+  - You should convert your provisioning profile to Base64 when saving it as a secret. In this example, the secret is named `BUILD_PROVISION_PROFILE_BASE64`.
+
+  - Use the following command to convert your provisioning profile to Base64 and copy it to your clipboard:
+  
+    ```shell
+    base64 <em>provisioning_profile.mobileprovision</em> | pbcopy
+    ```
+
+* A keychain password.
+
+  - A new keychain will be created on the runner, so the password for the new keychain can be any new random string. In this example, the secret is named `KEYCHAIN_PASSWORD`.
+
+### Add a step to your workflow
+
+This example workflow includes a step that imports the Apple certificate and provisioning profile from the {% data variables.product.prodname_dotcom %} secrets, and installs them on the runner.
+
+{% raw %}
+```yaml{:copy}
+name: App build
+on: push
+
+jobs:
+  build_with_signing:
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Install the Apple certificate and provisioning profile
+        env:
+          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
+          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
+          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}
+          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
+        run: |
+          # create variables
+          CERTIFICATE_PATH=$RUNNER_TEMP/build_certificate.p12
+          PP_PATH=$RUNNER_TEMP/build_pp.mobileprovision
+          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
+
+          # import certificate and provisioning profile from secrets
+          echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode --output $CERTIFICATE_PATH
+          echo -n "$BUILD_PROVISION_PROFILE_BASE64" | base64 --decode --output $PP_PATH
+
+          # create temporary keychain
+          security create-keychain -p $KEYCHAIN_PASSWORD $KEYCHAIN_PATH
+          security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
+          security unlock-keychain -p $KEYCHAIN_PASSWORD $KEYCHAIN_PATH
+
+          # import certificate to keychain
+          security import $CERTIFICATE_PATH -P $P12_PASSWORD -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
+          security list-keychain -d user -s $KEYCHAIN_PATH
+
+          # apply provisioning profile
+          mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
+          cp $PP_PATH ~/Library/MobileDevice/Provisioning\ Profiles
+      - name: Build app
+        ...
+```
+{% endraw %}
+
+### Required clean-up on self-hosted runners
+
+{% data variables.product.prodname_dotcom %}-hosted runners are isolated virtual machines that are automatically destroyed at the end of the job execution. This means that the certificates and provisioning profile used on the runner during the job will be destroyed with the runner when the job is completed.
+
+On self-hosted runners, the `$RUNNER_TEMP` directory is cleaned up at the end of the job execution, but the keychain and provisioning profile might still exist on the runner.
+
+If you use self-hosted runners, you should add a final step to your workflow to help ensure that these sensitive files are deleted at the end of the job. The workflow step shown below is an example of how to do this.
+
+{% raw %}
+```yaml
+- name: Clean up keychain and provisioning profile
+  if: ${{ always() }}
+  run: |
+    security delete-keychain $RUNNER_TEMP/app-signing.keychain-db
+    rm ~/Library/MobileDevice/Provisioning\ Profiles/build_pp.mobileprovision
+```
+{% endraw %}

content/actions/guides/installing-an-apple-certificate-on-macos-runners-for-xcode-development.md

@@ -54,6 +54,7 @@ We strongly recommend that actions use environment variables to access the files
 | `GITHUB_WORKFLOW` | The name of the workflow. |
 | `GITHUB_RUN_ID` | {% data reusables.github-actions.run_id_description %} |
 | `GITHUB_RUN_NUMBER` | {% data reusables.github-actions.run_number_description %} |
+| `GITHUB_JOB` | The [job_id](/actions/reference/workflow-syntax-for-github-actions#jobsjob_id) of the current job. |
 | `GITHUB_ACTION` | The unique identifier (`id`) of the action. |
 | `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`. |

content/actions/reference/environment-variables.md

@@ -16,7 +16,7 @@ versions:
 You can configure environments with protection rules and secrets. When a workflow job references an environment, the job won't start until all of the environment's protection rules pass. A job also cannot access secrets that are defined in an environment until all the environment protection rules pass.
 
 {% if currentVersion == "free-pro-team@latest" %}
-Environment protection rules and environment secrets are only available on public repositories. If you convert a repository from public to private, any configured protection rules or environment secrets will be ignored, and you will not be able to configure any environments. If you convert your repository back to public, you will have access to any previously configured protection rules and environment secrets.
+Environment protection rules and environment secrets are only available on public repositories and private repositories on an enterprise plan. If you convert a repository from public to private on a non-enterprise plan, any configured protection rules or environment secrets will be ignored, and you will not be able to configure any environments. If you convert your repository back to public, you will have access to any previously configured protection rules and environment secrets.
 {% endif %}
 
 #### Environment protection rules

content/actions/reference/environments.md

@@ -22,6 +22,8 @@ Geo DNS, such as [Amazon's Route 53 service](http://docs.aws.amazon.com/Route53/
 
 Writing requests to the replica requires sending the data to the primary and all replicas. This means that the performance of all writes are limited by the slowest replica, although new geo-replicas can seed the majority of their data from existing co-located geo-replicas, rather than from the primary. Geo-replication will not add capacity to a {% data variables.product.prodname_ghe_server %} instance or solve performance issues related to insufficient CPU or memory resources. If the primary appliance is offline, active replicas will be unable to serve any read or write requests. 
 
+{% data reusables.enterprise_installation.replica-limit %}
+
 ### Monitoring a geo-replication configuration
 
 {% data reusables.enterprise_installation.monitoring-replicas %}

content/admin/enterprise-management/about-geo-replication.md

@@ -14,6 +14,8 @@ When you configure high availability, there is an automated setup of one-way, as
 
 {% data variables.product.prodname_ghe_server %} supports an active/passive configuration, where the replica appliance runs as a standby with database services running in replication mode but application services stopped.
 
+{% data reusables.enterprise_installation.replica-limit %}
+
 ### Targeted failure scenarios
 
 Use a high availability configuration for protection against:

content/admin/enterprise-management/about-high-availability-configuration.md

@@ -10,6 +10,8 @@ topics:
   - enterprise
 ---
 
+{% data reusables.enterprise_installation.replica-limit %}
+
 ### Creating a high availability replica
 
 1. Set up a new {% data variables.product.prodname_ghe_server %} appliance on your desired platform. The replica appliance should mirror the primary appliance's CPU, RAM, and storage settings. We recommend that you install the replica appliance in an independent environment. The underlying hardware, software, and network components should be isolated from those of the primary appliance. If you are a using a cloud provider, use a separate region or zone. For more information, see ["Setting up a {% data variables.product.prodname_ghe_server %} instance"](/enterprise/{{ currentVersion }}/admin/guides/installation/setting-up-a-github-enterprise-server-instance).

content/admin/enterprise-management/creating-a-high-availability-replica.md

@@ -64,12 +64,21 @@ You can use Markdown to format your message. For more information, see "[About w
 {% if currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
 ### Creating a mandatory message
 
-You can create a mandatory message that {% data variables.product.product_name %} will show to all users the first time they sign in after you save the message. The message appears in a pop-up window that the user must dismiss before the user can use {% data variables.product.product_location %}. Mandatory messages have a variety of uses.
+You can create a mandatory message that {% data variables.product.product_name %} will show to all users the first time they sign in after you save the message. The message appears in a pop-up window that the user must dismiss before the user can use {% data variables.product.product_location %}. 
+
+Mandatory messages have a variety of uses.
 
 - Providing onboarding information for new employees
 - Telling users how to get help with {% data variables.product.product_location %}
 - Ensuring that all users read your terms of service for using {% data variables.product.product_location %}
 
+{% note %}
+
+**Note:** After you configure a mandatory message for {% data variables.product.product_location %}, you cannot change or remove the message.
+
+{% endnote %}
+
+
 If you include Markdown checkboxes in the message, all checkboxes must be selected before the user can dismiss the message. For example, if you include your terms of service in the mandatory message, you can require that each user selects a checkbox to confirm the user has read the terms.
 
 Each time a user sees a mandatory message, an audit log event is created. The event includes the version of the message that the user saw. For more information see "[Audited actions](/admin/user-management/audited-actions)."

content/admin/user-management/customizing-user-messages-for-your-enterprise.md

@@ -51,12 +51,22 @@ Scanning code when someone pushes a change, and whenever a pull request is creat
 
 By default, the {% data variables.product.prodname_codeql_workflow %} uses the `on.push` event to trigger a code scan on every push to the default branch of the repository and any protected branches. For {% data variables.product.prodname_code_scanning %} to be triggered on a specified branch, the workflow must exist in that branch. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#on)."
 
+If you scan on push, then the results appear in the **Security** tab for your repository. For more information, see "[Managing code scanning alerts for your repository](/code-security/secure-coding/managing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository)."
+
+{% note %}
+
+**Note**: If you want {% data variables.product.prodname_code_scanning %} alerts to appear as pull request checks, you must use the `pull_request` event, described below.
+
+{% endnote %}
+
 #### Scanning pull requests
 
 The default {% data variables.product.prodname_codeql_workflow %} uses the `pull_request` event to trigger a code scan on pull requests targeted against the default branch. {% if currentVersion ver_gt "enterprise-server@2.21" %}The `pull_request` event is not triggered if the pull request was opened from a private fork.{% else %}If a pull request is from a private fork, the `pull_request` event will only be triggered if you've selected the "Run workflows from fork pull requests" option in the repository settings. For more information, see "[Disabling or limiting {% data variables.product.prodname_actions %} for a repository](/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository#enabling-workflows-for-private-repository-forks)."{% endif %}
 
 For more information about the `pull_request` event, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestbranchestags)."
 
+If you scan pull requests, then the results appear as alerts in a pull request check. For more information, see "[Triaging code scanning alerts in pull requests](/code-security/secure-coding/triaging-code-scanning-alerts-in-pull-requests)."
+
 #### Avoiding unnecessary scans of pull requests
 
 You might want to avoid a code scan being triggered on specific pull requests targeted against the default branch, irrespective of which files have been changed. You can configure this by specifying `on:pull_request:paths-ignore` or `on:pull_request:paths` in the {% data variables.product.prodname_code_scanning %} workflow. For example, if the only changes in a pull request are to files with the file extensions `.md` or `.txt` you can use the following `paths-ignore` array.