GitHub Enterprise Server 3.17 release candidate (#55411)

Co-authored-by: docs-bot <[email protected]>
Co-authored-by: Isaac Brown <[email protected]>
Co-authored-by: Pallavi <[email protected]>
Co-authored-by: Stephanie Sabota <[email protected]>
Co-authored-by: Casey Tucker <[email protected]>
Co-authored-by: Hao Jiang <[email protected]>
Co-authored-by: Felicity Chapman <[email protected]>
Co-authored-by: mc <[email protected]>

Author: 9 people

content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/integrating-jira-with-your-personal-projects.md

@@ -24,5 +24,6 @@ shortTitle: Integrate Jira with projects
 
 ## Further reading
 
-* [AUTOTITLE](/organizations/managing-organization-settings/integrating-jira-with-your-organization-project-board)
+{% ifversion projects-v1 %}
+* [AUTOTITLE](/organizations/managing-organization-settings/integrating-jira-with-your-organization-project-board){% endif %}
 * [Connect Jira Cloud to GitHub](https://confluence.atlassian.com/adminjiracloud/connect-jira-cloud-to-github-814188429.html) in the Atlassian documentation

content/admin/all-releases.md

@@ -52,6 +52,7 @@ If you run analysis in an external CI system, we recommend using the same versio
 
 | {% data variables.product.prodname_ghe_server %} version | Recommended {% data variables.product.prodname_codeql_cli %} version |
 | ------------------------------------------------- | ---------------------- |
+| 3.17 | 2.20.7 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.20.7/)) |
 | 3.16 | 2.20.3 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.20.3/)) |
 | 3.15 | 2.18.4 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.18.4/)) |
 | 3.14 | 2.17.6 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.17.6/)) |
@@ -70,6 +71,7 @@ For instances with {% data variables.product.prodname_actions %} enabled, self-h
 
 | {% data variables.product.prodname_ghe_server %} version | Minimum Runner version |
 | ------------------------------------------------- | ---------------------- |
+| 3.17 | 2.322.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.322.0)) |
 | 3.16 | 2.321.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.321.0)) |
 | 3.15 | 2.319.1 ([release notes](https://github.com/actions/runner/releases/tag/v2.319.1)) |
 | 3.14 | 2.317.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.317.0)) |

content/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/about-the-backup-service-for-github-enterprise-server.md

@@ -0,0 +1,54 @@
+---
+title: About the backup service for GitHub Enterprise Server
+shortTitle: About the backup service
+intro: 'Learn what the built-in backup service offers and how it differs from a High Availability replica.'
+versions:
+  ghes: '>=3.17'
+type: overview
+topics:
+  - Backups
+  - Enterprise
+  - Fundamentals
+  - Infrastructure
+---
+
+>[!NOTE] {% data variables.product.prodname_enterprise_backup_service %} is currently in {% data variables.release-phases.public_preview %} and is subject to change. During the public preview, the service is available at no additional cost.
+
+## About the {% data variables.product.prodname_enterprise_backup_service %}
+
+The {% data variables.product.prodname_enterprise_backup_service %} is a managed backup solution built directly into {% data variables.product.prodname_ghe_server %}. It offers a simplified alternative to the legacy {% data variables.product.prodname_enterprise_backup_utilities %}.
+
+With this service, you can:
+
+* Configure scheduled backups from the {% data variables.enterprise.management_console %}.
+* View backup status and history.
+
+Compared to the legacy backup utilities, the {% data variables.product.prodname_enterprise_backup_service %}:
+
+* Can be configured through the {% data variables.enterprise.management_console %}.
+* Doesn’t require a separate host for backup software.
+* Stores backups on a dedicated storage volume directly accessible by your instance.
+
+>[!NOTE] {% data variables.product.prodname_enterprise_backup_service %} is currently only supported on standalone instances and high availability primary nodes. Cluster configurations and replica nodes are not yet supported.
+
+## How does the backup service differ from a High Availability replica?
+
+While both the backup service and a High Availability (HA) replica contribute to data protection, they serve different purposes and are recommended together for a robust deployment.
+
+### High Availability replica
+
+An HA replica is a redundant, passive {% data variables.product.prodname_ghe_server %} instance that stays in sync with the primary instance via datastore replication. It minimizes service disruption during hardware failure or network outages.
+
+However, it’s not a replacement for backups—because any data corruption or loss on the primary can be immediately replicated to the HA node.
+
+### {% data variables.product.prodname_enterprise_backup_service %}
+
+The backup service is a disaster recovery solution. It captures full, timestamped snapshots of instance data that can be used to restore an instance or spin up a new one—without needing an always-on replica.
+
+## Further reading
+
+* [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance)
+* [About {% data variables.product.prodname_enterprise_backup_utilities %}](https://github.com/github/backup-utils#readme)
+* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh)
+* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode)
+* [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled)

content/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/backup-service-settings-reference.md

@@ -0,0 +1,46 @@
+---
+title: Backup service settings reference
+shortTitle: Backup settings
+intro: 'Reference for all configurable options available in the Backup Service section of the {% data variables.enterprise.management_console %}.'
+versions:
+  ghes: '>= 3.17'
+type: reference
+topics:
+  - Backups
+---
+
+You can configure the following options in the "Backup Service" section of the {% data variables.enterprise.management_console %}.
+
+## Snapshot retention
+
+* **Number of snapshots**: Sets how many backup snapshots to retain (default: `10`). Older snapshots are automatically pruned after each successful backup.
+
+## Restore options
+
+* **Skip audit logs restore**: Excludes audit logs during a restore.
+* **Restore Management Console password**: If enabled, restores the root site admin password from snapshot data (default: `true`).
+
+## Performance tuning
+
+* **Process priority**:
+
+  * **Nice**: Sets the CPU scheduling priority (`nice -n 19` by default).
+  * **Ionice**: Sets the I/O scheduling priority (`ionice -c 3` by default).
+
+* **Rsync compression**: Uses compression for `rsync` transfers during backup and restore, reducing bandwidth usage.
+
+## MSSQL backup schedule
+
+* **MSSQL backup cadence**: Sets the schedule for full, differential, and transaction log backups, in minutes (default: `10080,1440,15`).
+
+## Backup content
+
+* **Include Pages**: Adds {% data variables.product.prodname_pages %} data to snapshots.
+* **Skip search indices**: Excludes search index data from snapshots.
+
+## Parallelization settings
+
+* **Enable parallel jobs**: Allows multiple backup jobs to run concurrently.
+* **Max jobs**: Limits the total number of parallel backup jobs.
+* **Max rsync jobs**: Limits the number of parallel `rsync` jobs.
+* **Max system load**: Sets a load limit to throttle parallel processing when needed.

content/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/configuring-the-backup-service.md

@@ -0,0 +1,120 @@
+---
+title: Configuring the backup service
+shortTitle: Configure the backup service
+intro: 'Enable and configure the built-in backup service in the {% data variables.enterprise.management_console %}, and optionally migrate legacy settings.'
+versions:
+  ghes: '>=3.17'
+type: how_to
+topics:
+  - Backups
+  - Enterprise
+  - Fundamentals
+  - Infrastructure
+---
+
+Before configuring the backup service, ensure you have:
+
+* A {% data variables.product.prodname_ghe_server %} instance running version 3.17 or later.
+* A dedicated storage volume provisioned and managed for use as the backup target.
+
+## Storage requirements
+
+To ensure reliable and performant backups, your storage must meet the following requirements:
+
+* **Capacity:** Allocate at least five times the amount of storage used by your primary {% data variables.product.github %} appliance disk. This accounts for historical snapshots and future growth.
+* **Filesystem support:** The backup service uses hard links for efficient storage, and your {% data variables.product.github %} instance uses symbolic links. The backup target must support both symbolic and hard links, and it must use a case-sensitive filesystem to prevent conflicts.
+
+  You can test whether your filesystem supports hardlinking symbolic links by running:
+
+    ```shell
+    touch file
+    ln -s file symlink
+    ln symlink hardlink
+    ls -la
+    ```
+
+    If the `ln symlink hardlink` command completes successfully, the filesystem is supported.
+
+* **Performance:** Use high-performance storage with low latency and high IOPS to avoid slow backups and restores.
+* **NFS:** Avoid using an NFS mount for the backup directory (typically `/data/backup`), as this can lead to timeouts and degraded performance.
+
+## Configuring the backup service
+
+You can configure {% data variables.product.prodname_enterprise_backup_service %} through the {% data variables.enterprise.management_console %}.
+
+### Setting up the backup target
+
+Before configuring the service, you must prepare the storage volume where backups will be stored.
+
+#### Using a new block device
+
+If you're using a dedicated block device as your backup target, you need to initialize it via SSH before proceeding in the {% data variables.enterprise.management_console %}. This process will **format the device and erase all existing data**.
+
+1. Connect to your instance via SSH as the `admin` user. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh).
+1. Attach your backup block device to the instance.
+1. Identify the device name using `lsblk` to list available block devices. Make sure you select the correct device to avoid data loss.
+
+    ```shell
+    lsblk
+    ```
+
+1. Run the initialization command, replacing `YOUR_DEVICE_NAME` with the actual device name identified in the previous step.
+
+    >[!WARNING] This command will permanently erase all data on the specified device. Double-check the device name and back up any important data before proceeding.
+
+    ```shell
+    ghe-storage-init-backup /dev/YOUR_DEVICE_NAME
+    ```
+
+    This command:
+    * Formats the device (erases all data).
+    * Prepares it for use by the backup service.
+    * Sets it to mount automatically at `/data/backup` on boot.
+
+#### Reusing a previously initialized disk
+
+If the device was already initialized using `ghe-storage-init-backup`, you can reuse it without reformatting:
+
+1. Connect to your instance via SSH as the `admin` user.
+1. Attach the disk to the instance.
+1. Create the mount point, if it doesn't exist.
+
+   ```shell
+   sudo mkdir -p /data/backup
+   ```
+
+1. Enable and start the mount service.
+
+   ```shell
+   sudo systemctl enable ghe-backup-disk.service
+   sudo systemctl start ghe-backup-disk.service
+   ```
+
+   This will mount the device at `/data/backup` and ensures it's mounted automatically in the future.
+
+### Configuring backup settings
+
+After the backup target is mounted, the Backup Service page will become available in the {% data variables.enterprise.management_console %}. If you're using a block device, this requires completing the initialization or mount steps above.
+
+>[!NOTE] The settings page won’t appear until the backup storage is mounted at `/data/backup`.
+
+If you're migrating from {% data variables.product.prodname_enterprise_backup_utilities %}, you can transfer your configuration in one of two ways:
+
+1. **Manual configuration**: Recreate your settings directly in the {% data variables.enterprise.management_console %}.
+1. **Command-line migration**: SSH into your instance, copy your `backup.config` file from backup-utils, and run:
+
+   ```shell
+   ghe-migrate-backup-config /path/to/your/backup.config
+   ```
+
+   Use the `--dry-run` flag to preview changes without applying them.
+
+### Scheduling automated backups
+
+Once the service is configured, you can define a backup schedule.
+
+1. In the {% data variables.enterprise.management_console %}, open the "Backup Service" page.
+1. In the "Backup Schedule" section, choose a predefined schedule (e.g., Daily) or enter a custom cron expression.
+1. Click **Save** to apply the changes.
+
+The first run will be a full backup. Future runs will be incremental. If a new backup attempt starts while a previous one is still running, it may be skipped or fail. In that case, adjust the schedule to avoid overlap.

content/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/creating-and-monitoring-backups.md

@@ -0,0 +1,70 @@
+---
+title: Creating and monitoring backups
+shortTitle: Create and monitor backups
+intro: 'Run manual backups, understand backup types, and monitor backup activity using the {% data variables.enterprise.management_console %} or command line.'
+versions:
+  ghes: '>= 3.17'
+type: how_to
+topics:
+  - Backups
+  - Monitoring
+---
+
+## About backup types
+
+{% data variables.product.prodname_enterprise_backup_service %} supports two types of backups:
+
+* **Full backups**: Capture a complete snapshot of all data. The first backup is always a full backup.
+* **Incremental backups**: Include only changes since the last backup, significantly reducing backup time and storage usage.
+
+The system automatically determines which type to create based on the schedule and backup history. For Git repositories and other file stores, hard links are used to ensure storage-efficient snapshots with full point-in-time recovery.
+
+## Creating backups
+
+Once the backup service is configured, it will automatically create backups based on your defined schedule. You can also trigger backups manually as needed.
+
+### Running a manual backup
+
+To create an on-demand backup—for example, before performing maintenance:
+
+1. Connect to your instance via SSH as the `admin` user. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh).
+1. Run the backup command:
+
+   ```shell
+   ghe-backup
+   ```
+
+### Command line backup utilities
+
+You can also use these CLI tools for advanced backup management or troubleshooting:
+
+* `ghe-backup`: Triggers a full or incremental backup, depending on the state.
+* `ghe-prune-snapshots`: Deletes old snapshots based on your configured retention policy.
+
+## Monitoring backups
+
+You can monitor backup activity through the {% data variables.enterprise.management_console %} or from the command line.
+
+### Viewing backup status in the {% data variables.enterprise.management_console %}
+
+1. On the "Backup Service" page, navigate to the "Backup History" section.
+1. Review the status of recent backups.
+
+### Monitoring via SSH
+
+To check backup progress or troubleshoot issues from the command line:
+
+1. SSH into your instance as the `admin` user.
+1. View the most recent backup log:
+
+   ```shell
+   cat /var/log/github-backup/backup-verbose-$(date +%Y%m%d).log
+   ```
+
+1. To check if a backup is currently running, look for this file:
+
+   ```shell
+   ls /data/user/common/backup_utils_in_progress
+   ```
+
+   If the file exists, a backup is currently running.

content/admin/backing-up-and-restoring-your-instance/backup-service-for-github-enterprise-server/index.md

@@ -0,0 +1,18 @@
+---
+title: Backup service for GitHub Enterprise Server
+shortTitle: Backup service
+intro: '{% data variables.product.github %} offers a managed backup solution built directly into {% data variables.product.prodname_ghe_server %} to protect your instance data.'
+versions:
+  ghes: '>=3.17'
+topics:
+  - Enterprise
+children:
+  - /about-the-backup-service-for-github-enterprise-server
+  - /understanding-the-backup-service
+  - /configuring-the-backup-service
+  - /creating-and-monitoring-backups
+  - /restoring-from-a-backup
+  - /restoring-with-github-actions-enabled
+  - /backup-service-settings-reference
+  - /understanding-the-snapshot-file-structure
+---