diff --git a/content/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled.md b/content/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled.md index 203f3fa1fb..bd71918b12 100644 --- a/content/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled.md +++ b/content/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled.md @@ -1,7 +1,7 @@ --- title: Backing up and restoring GitHub Enterprise Server with GitHub Actions enabled shortTitle: Backing up and restoring -intro: '{% data variables.product.prodname_actions %} data on your external storage provider is not included in regular {% data variables.product.prodname_ghe_server %} backups, and must be backed up separately.' +intro: 'To restore a backup of {% data variables.product.product_location %} when {% data variables.product.prodname_actions %} is enabled, you must configure {% data variables.product.prodname_actions %} before restoring the backup with {% data variables.product.prodname_enterprise_backup_utilities %}.' versions: ghes: '*' type: how_to @@ -13,43 +13,32 @@ topics: redirect_from: - /admin/github-actions/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled --- -{% data reusables.actions.enterprise-storage-ha-backups %} -If you use {% data variables.product.prodname_enterprise_backup_utilities %} to back up {% data variables.product.product_location %}, it's important to note that {% data variables.product.prodname_actions %} data stored on your external storage provider is not included in the backup. +## About backups of {% data variables.product.product_name %} when using {% data variables.product.prodname_actions %} -This is an overview of the steps required to restore {% data variables.product.product_location %} with {% data variables.product.prodname_actions %} to a new appliance: +You can use {% data variables.product.prodname_enterprise_backup_utilities %} to back up and restore the data and configuration for {% data variables.product.product_location %} to a new instance. For more information, see "[Configuring backups on your appliance](/admin/configuration/configuring-backups-on-your-appliance)." -1. Confirm that the original appliance is offline. -1. Manually configure network settings on the replacement {% data variables.product.prodname_ghe_server %} appliance. Network settings are excluded from the backup snapshot, and are not overwritten by `ghe-restore`. -1. To configure the replacement appliance to use the same {% data variables.product.prodname_actions %} external storage configuration as the original appliance, from the new appliance, set the required parameters with `ghe-config` command. - - - Azure Blob Storage - ```shell - ghe-config secrets.actions.storage.blob-provider "azure" - ghe-config secrets.actions.storage.azure.connection-string "_Connection_String_" - ``` - - Amazon S3 - ```shell - ghe-config secrets.actions.storage.blob-provider "s3" - ghe-config secrets.actions.storage.s3.bucket-name "_S3_Bucket_Name" - ghe-config secrets.actions.storage.s3.service-url "_S3_Service_URL_" - ghe-config secrets.actions.storage.s3.access-key-id "_S3_Access_Key_ID_" - ghe-config secrets.actions.storage.s3.access-secret "_S3_Access_Secret_" - ``` - - Optionally, to enable S3 force path style, enter the following command: - ```shell - ghe-config secrets.actions.storage.s3.force-path-style true - ``` - +However, not all the data for {% data variables.product.prodname_actions %} is included in these backups. {% data reusables.actions.enterprise-storage-ha-backups %} -1. Enable {% data variables.product.prodname_actions %} on the replacement appliance. This will connect the replacement appliance to the same external storage for {% data variables.product.prodname_actions %}. +## Restoring a backup of {% data variables.product.product_name %} when {% data variables.product.prodname_actions %} is enabled - ```shell - ghe-config app.actions.enabled true - ghe-config-apply - ``` +To restore a backup of {% data variables.product.product_location %} with {% data variables.product.prodname_actions %}, you must manually configure network settings and external storage on the destination instance before you restore your backup from {% data variables.product.prodname_enterprise_backup_utilities %}. -1. After {% data variables.product.prodname_actions %} is configured and enabled, use the `ghe-restore` command to restore the rest of the data from the backup. For more information, see "[Restoring a backup](/admin/configuration/configuring-backups-on-your-appliance#restoring-a-backup)." -1. Re-register your self-hosted runners on the replacement appliance. For more information, see [Adding self-hosted runners](/actions/hosting-your-own-runners/adding-self-hosted-runners). +1. Confirm that the source instance is offline. +1. Manually configure network settings on the replacement {% data variables.product.prodname_ghe_server %} instance. Network settings are excluded from the backup snapshot, and are not overwritten by `ghe-restore`. For more information, see "[Configuring network settings](/admin/configuration/configuring-network-settings)." +1. SSH into the destination instance. For more information, see "[Accessing the administrative shell (SSH)](/admin/configuration/accessing-the-administrative-shell-ssh)." -For more information on backing up and restoring {% data variables.product.prodname_ghe_server %}, see "[Configuring backups on your appliance](/admin/configuration/configuring-backups-on-your-appliance)." + ```shell{:copy} + $ ssh -p 122 admin@HOSTNAME + ``` +1. Configure the destination instance to use the same external storage service for {% data variables.product.prodname_actions %} as the source instance by entering one of the following commands. +{% indented_data_reference reusables.actions.configure-storage-provider-platform-commands spaces=3 %} +{% data reusables.actions.configure-storage-provider %} +1. To prepare to enable {% data variables.product.prodname_actions %} on the destination instance, enter the following command. + + ```shell{:copy} + ghe-config app.actions.enabled true + ``` +{% data reusables.actions.apply-configuration-and-enable %} +1. After {% data variables.product.prodname_actions %} is configured and enabled, to restore the rest of the data from the backup, use the `ghe-restore` command. For more information, see "[Restoring a backup](/admin/configuration/configuring-backups-on-your-appliance#restoring-a-backup)." +1. Re-register your self-hosted runners on the destination instance. For more information, see "[Adding self-hosted runners](/actions/hosting-your-own-runners/adding-self-hosted-runners)." diff --git a/content/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance.md b/content/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance.md index d82586d25b..6fa069a0f2 100644 --- a/content/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance.md +++ b/content/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance.md @@ -5,13 +5,14 @@ redirect_from: - /enterprise/admin/installation/setting-up-a-staging-instance - /admin/installation/setting-up-a-staging-instance versions: - ghes: '*' + ghes: "*" type: how_to topics: - Enterprise - Infrastructure - Upgrades shortTitle: Set up a staging instance +miniTocMaxHeadingLevel: 3 --- ## About staging instances @@ -38,10 +39,118 @@ To thoroughly test {% data variables.product.product_name %} and recreate an env ## Setting up a staging instance -1. Perform a backup of your production instance using {% data variables.product.prodname_enterprise_backup_utilities %}. For more information, see the "About {% data variables.product.prodname_enterprise_backup_utilities %}" section of "[Configuring backups on your appliance](/enterprise/admin/guides/installation/configuring-backups-on-your-appliance#about-github-enterprise-server-backup-utilities)." -2. Set up a new instance to act as your staging environment. You can use the same guides for provisioning and installing your staging instance as you did for your production instance. For more information, see "[Setting up a {% data variables.product.prodname_ghe_server %} instance](/enterprise/admin/guides/installation/setting-up-a-github-enterprise-server-instance/)." -3. Optionally, if you plan to test {% data variables.product.prodname_actions %} functionality in your test environment, review the considerations for your logs and storage. For more information, see "[Using a staging environment](/admin/github-actions/advanced-configuration-and-troubleshooting/using-a-staging-environment)." -4. Restore your backup onto your staging instance. For more information, see the "Restoring a backup" section of "[Configuring backups on your appliance](/enterprise/admin/guides/installation/configuring-backups-on-your-appliance#restoring-a-backup)." +You can set up a staging instance from scratch and configure the instance however you like. For more information, see "[Setting up a {% data variables.product.product_name %} instance](/admin/installation/setting-up-a-github-enterprise-server-instance)" and "[Configuring your enterprise](/admin/configuration/configuring-your-enterprise)." + +Alternatively, you can create a staging instance that reflects your production configuration by restoring a backup of your production instance to the staging instance. + +1. [Back up your production instance](#1-back-up-your-production-instance). +2. [Set up a staging instance](#2-set-up-a-staging-instance). +3. [Configure {% data variables.product.prodname_actions %}](#3-configure-github-actions). +4. [Configure {% data variables.product.prodname_registry %}](#4-configure-github-packages). +5. [Restore your production backup](#5-restore-your-production-backup). +6. [Review the instance's configuration](#6-review-the-instances-configuration). +7. [Apply the instance's configuration](#7-apply-the-instances-configuration). + +### 1. Back up your production instance + +If you want to test changes on an instance that contains the same data and configuration as your production instance, back up the data and configuration from the production instance using {% data variables.product.prodname_enterprise_backup_utilities %}. For more information, see "[Configuring backups on your appliance](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance)." + +{% warning %} + +**Warning**: If you use {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %} in production, your backup will include your production configuration for external storage. To avoid potential loss of data by writing to your production storage from your staging instance, you must configure each feature in steps 3 and 4 before you restore your backup. + +{% endwarning %} + +### 2. Set up a staging instance + +Set up a new instance to act as your staging environment. You can use the same guides for provisioning and installing your staging instance as you did for your production instance. For more information, see "[Setting up a {% data variables.product.prodname_ghe_server %} instance](/enterprise/admin/guides/installation/setting-up-a-github-enterprise-server-instance/)." + +If you plan to restore a backup of your production instance, continue to the next step. Alternatively, you can configure the instance manually and skip the following steps. + +### 3. Configure {% data variables.product.prodname_actions %} + +Optionally, if you use {% data variables.product.prodname_actions %} on your production instance, configure the feature on the staging instance before restoring your production backup. If you don't use {% data variables.product.prodname_actions %}, skip to "[4. Configure {% data variables.product.prodname_registry %}](#4-configure-github-packages)." + +{% warning %} + +**Warning**: If you don't configure {% data variables.product.prodname_actions %} on the staging instance before restoring your production backup, your staging instance will use your production instance's external storage, which could result in loss of data. We strongly recommended that you use different external storage for your staging instance. For more information, see "[Using a staging environment](/admin/github-actions/advanced-configuration-and-troubleshooting/using-a-staging-environment)." + +{% endwarning %} + +{% data reusables.enterprise_installation.ssh-into-staging-instance %} +1. To configure the staging instance to use an external storage provider for {% data variables.product.prodname_actions %}, enter one of the following commands. +{% indented_data_reference reusables.actions.configure-storage-provider-platform-commands spaces=3 %} +{% data reusables.actions.configure-storage-provider %} +1. To prepare to enable {% data variables.product.prodname_actions %} on the staging instance, enter the following command. + + ```shell{:copy} + ghe-config app.actions.enabled true + ``` + +### 4. Configure {% data variables.product.prodname_registry %} + +Optionally, if you use {% data variables.product.prodname_registry %} on your production instance, configure the feature on the staging instance before restoring your production backup. If you don't use {% data variables.product.prodname_registry %}, skip to "[5. Restore your production backup](#5-restore-your-production-backup)." + +{% warning %} + +**Warning**: If you don't configure {% data variables.product.prodname_actions %} on the staging instance before restoring your production backup, your staging instance will use your production instance's external storage, which could result in loss of data. We strongly recommended that you use different external storage for your staging instance. + +{% endwarning %} + +1. Review the backup you will restore to the staging instance. + - If you took the backup with {% data variables.product.prodname_enterprise_backup_utilities %} 3.5 or later, the backup includes the configuration for {% data variables.product.prodname_registry %}. Continue to the next step. + - If you took the backup with {% data variables.product.prodname_enterprise_backup_utilities %} 3.4 or earlier, configure {% data variables.product.prodname_registry %} on the staging instance. For more information, see "[Getting started with {% data variables.product.prodname_registry %} for your enterprise](/admin/packages/getting-started-with-github-packages-for-your-enterprise)." +{% data reusables.enterprise_installation.ssh-into-staging-instance %} +1. Configure the external storage connection by entering the following commands, replacing the placeholder values with actual values for your connection. + - Azure Blob Storage: + + ```shell{:copy} + ghe-config secrets.packages.blob-storage-type "azure" + ghe-config secrets.packages.azure-container-name "AZURE CONTAINER NAME" + ghe-config secrets.packages.azure-connection-string "CONNECTION STRING" + ``` + - Amazon S3: + + ```shell{:copy} + ghe-config secrets.packages.blob-storage-type "s3" + ghe-config secrets.packages.service-url "S3 SERVICE URL" + ghe-config secrets.packages.s3-bucket "S3 BUCKET NAME" + ghe-config secrets.packages.aws-access-key "S3 ACCESS KEY ID" + ghe-config secrets.packages.aws-secret-key "S3 ACCESS SECRET" + ``` +1. To prepare to enable {% data variables.product.prodname_registry %} on the staging instance, enter the following command. + + ```shell{:copy} + ghe-config app.packages.enabled true + ``` + +### 5. Restore your production backup + +Use the `ghe-restore` command to restore the rest of the data from the backup. For more information, see "[Restoring a backup](/admin/configuration/configuring-backups-on-your-appliance#restoring-a-backup)." + +If the staging instance is already configured and you're about to overwrite settings, certificate, and license data, add the `-c` option to the command. For more information about the option, see [Using the backup and restore commands](https://github.com/github/backup-utils/blob/master/docs/usage.md#restoring-settings-tls-certificate-and-license) in the {% data variables.product.prodname_enterprise_backup_utilities %} documentation. + +### 6. Review the instance's configuration + +To access the staging instance using the same hostname, update your local hosts file to resolve the staging instance's hostname by IP address by editing the `/etc/hosts` file in macOS or Linux, or the `C:\Windows\system32\drivers\etc` file in Windows. + +{% note %} + +**Note**: Your staging instance must be accessible from the same hostname as your production instance. Changing the hostname for {% data variables.product.product_location %} is not supported. For more information, see "[Configuring a hostname](/admin/configuration/configuring-network-settings/configuring-a-hostname)." + +{% endnote %} + +Then, review the staging instance's configuration in the {% data variables.enterprise.management_console %}. For more information, see "[Accessing the {% data variables.enterprise.management_console %}](/admin/configuration/configuring-your-enterprise/accessing-the-management-console)." + +{% warning %} + +**Warning**: If you configured {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %} for the staging instance, to avoid overwriting production data, ensure that the external storage configuration in the {% data variables.enterprise.management_console %} does not match your production instance. + +{% endwarning %} + +### 7. Apply the instance's configuration + +To apply the configuration from the {% data variables.enterprise.management_console %}, click **Save settings**. ## Further reading diff --git a/data/reusables/actions/apply-configuration-and-enable.md b/data/reusables/actions/apply-configuration-and-enable.md new file mode 100644 index 0000000000..4794ca96fc --- /dev/null +++ b/data/reusables/actions/apply-configuration-and-enable.md @@ -0,0 +1,5 @@ +1. To apply the configuration and enable {% data variables.product.prodname_actions %} to connect to your external storage provider, enter the following command. + + ```shell{:copy} + ghe-config-apply + ``` diff --git a/data/reusables/actions/configure-storage-provider-platform-commands.md b/data/reusables/actions/configure-storage-provider-platform-commands.md new file mode 100644 index 0000000000..7fe2767e34 --- /dev/null +++ b/data/reusables/actions/configure-storage-provider-platform-commands.md @@ -0,0 +1,10 @@ +- Azure Blob Storage: + + ```shell{:copy} + ghe-config secrets.actions.storage.blob-provider "azure" + ``` +- Amazon S3: + + ```shell{:copy} + ghe-config secrets.actions.storage.blob-provider "s3" + ``` diff --git a/data/reusables/actions/configure-storage-provider.md b/data/reusables/actions/configure-storage-provider.md new file mode 100644 index 0000000000..a2858c74b6 --- /dev/null +++ b/data/reusables/actions/configure-storage-provider.md @@ -0,0 +1,20 @@ +1. Configure the external storage connection by entering the following commands, replacing the placeholder values with actual values for your connection. + + - Azure Blob Storage: + + ```shell{:copy} + ghe-config secrets.actions.storage.azure.connection-string "CONNECTION STRING" + ``` + - Amazon S3: + + ```shell{:copy} + ghe-config secrets.actions.storage.s3.bucket-name "S3 BUCKET NAME" + ghe-config secrets.actions.storage.s3.service-url "S3 SERVICE URL" + ghe-config secrets.actions.storage.s3.access-key-id "S3 ACCESS KEY ID" + ghe-config secrets.actions.storage.s3.access-secret "S3 ACCESS SECRET" + ``` + Optionally, to force path-style addressing for S3, also enter the following command. + + ```shell{:copy} + ghe-config secrets.actions.storage.s3.force-path-style true + ``` diff --git a/data/reusables/enterprise_installation/ssh-into-staging-instance.md b/data/reusables/enterprise_installation/ssh-into-staging-instance.md new file mode 100644 index 0000000000..017373c533 --- /dev/null +++ b/data/reusables/enterprise_installation/ssh-into-staging-instance.md @@ -0,0 +1,5 @@ +1. SSH into the staging instance. For more information, see "[Accessing the administrative shell (SSH)](/admin/configuration/accessing-the-administrative-shell-ssh)." + + ```shell{:copy} + $ ssh -p 122 admin@HOSTNAME + ```