diff --git a/assets/images/help/repository/tags-download-zip-targz.png b/assets/images/help/repository/tags-download-zip-targz.png new file mode 100644 index 000000000000..bfc8c2388e0c Binary files /dev/null and b/assets/images/help/repository/tags-download-zip-targz.png differ diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise.md index 0c46ce1a0b23..db0790bdc7bc 100644 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise.md +++ b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise.md @@ -1093,7 +1093,7 @@ Before you'll see `git` category actions, you must enable Git events in the audi {%- ifversion ghes %} | `repo.disk_archive` | A repository was archived on disk. For more information, see "[AUTOTITLE](/repositories/archiving-a-github-repository/archiving-repositories)." {%- endif %} -| `repo.download_zip` | A source code archive of a repository was downloaded as a ZIP file. +| `repo.download_zip` | A source code archive of a repository was downloaded as a ZIP file. For more information, see "[AUTOTITLE](/repositories/working-with-files/using-files/downloading-source-code-archives)." | `repo.pages_cname` | A {% data variables.product.prodname_pages %} custom domain was modified in a repository. | `repo.pages_create` | A {% data variables.product.prodname_pages %} site was created. | `repo.pages_destroy` | A {% data variables.product.prodname_pages %} site was deleted. diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md index 137f5630ef08..db28b430a4d8 100644 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md +++ b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md @@ -684,7 +684,7 @@ For more information, see "[AUTOTITLE](/organizations/managing-organization-sett | `create_actions_secret` |Triggered when a {% data variables.product.prodname_actions %} secret is created for a repository. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)."{% endif %} | `destroy` | Triggered when [a repository is deleted](/repositories/creating-and-managing-repositories/deleting-a-repository).{% ifversion fpt or ghec %} | `disable` | Triggered when a repository is disabled (e.g., for [insufficient funds](/billing/managing-your-github-billing-settings/unlocking-a-locked-account)).{% endif %} -| `download_zip` | A source code archive of a repository was downloaded as a ZIP file. +| `download_zip` | A source code archive of a repository was downloaded as a ZIP file. For more information, see "[AUTOTITLE](/repositories/working-with-files/using-files/downloading-source-code-archives)." | `enable` | Triggered when a repository is re-enabled.{% ifversion fpt or ghes or ghec %} | `remove_actions_secret` | Triggered when a {% data variables.product.prodname_actions %} secret is removed.{% endif %} | `remove_member` | Triggered when a user is [removed from a repository as a collaborator](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository). diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository.md index 10e5a52093a6..5720f28d2281 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository.md @@ -14,7 +14,7 @@ redirect_from: --- ## About {% data variables.large_files.product_name_short %} objects in archives -{% data variables.product.product_name %} creates source code archives of your repository in the form of ZIP files and tarballs. People can download these archives on the main page of your repository or as release assets. By default, {% data variables.large_files.product_name_short %} objects are not included in these archives, only the pointer files to these objects. To improve the usability of archives for your repository, you can choose to include the {% data variables.large_files.product_name_short %} objects instead. To be included, the {% data variables.large_files.product_name_short %} objects must be covered by tracking rules in a *.gitattributes* file that has been committed to the repository. +{% data variables.product.product_name %} creates [source code archives](/repositories/working-with-files/using-files/downloading-source-code-archives) of your repository in the form of ZIP files and tarballs. People can download these archives on the main page of your repository or as release assets. By default, {% data variables.large_files.product_name_short %} objects are not included in these archives, only the pointer files to these objects. To improve the usability of archives for your repository, you can choose to include the {% data variables.large_files.product_name_short %} objects instead. To be included, the {% data variables.large_files.product_name_short %} objects must be covered by tracking rules in a *.gitattributes* file that has been committed to the repository. If you choose to include {% data variables.large_files.product_name_short %} objects in archives of your repository, every download of those archives will count towards bandwidth usage for your account. Each account receives {% data variables.large_files.initial_bandwidth_quota %} per month of bandwidth for free, and you can pay for additional usage. For more information, see "[AUTOTITLE](/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage)" and "[AUTOTITLE](/billing/managing-billing-for-git-large-file-storage)." diff --git a/content/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage.md b/content/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage.md index 5c9711fc53ec..68564466f148 100644 --- a/content/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage.md +++ b/content/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage.md @@ -24,7 +24,7 @@ For example: - If {% data variables.product.prodname_actions %} downloads a 500 MB file that is tracked with LFS, it will use 500 MB of the repository owner's allotted bandwidth. {% ifversion fpt or ghec %} -If {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) objects are included in source code archives for your repository, downloads of those archives will count towards bandwidth usage for the repository. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository)." +If {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) objects are included in [source code archives](/repositories/working-with-files/using-files/downloading-source-code-archives) for your repository, downloads of those archives will count towards bandwidth usage for the repository. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository)." {% endif %} {% tip %} diff --git a/content/repositories/working-with-files/using-files/downloading-source-code-archives.md b/content/repositories/working-with-files/using-files/downloading-source-code-archives.md new file mode 100644 index 000000000000..6e92ebcb516a --- /dev/null +++ b/content/repositories/working-with-files/using-files/downloading-source-code-archives.md @@ -0,0 +1,74 @@ +--- +title: Downloading source code archives +intro: 'You can download a snapshot of the code in your repository.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - Repositories +shortTitle: Source code archives +--- +## Overview of source code archives + +You can download a snapshot of any branch, tag, or specific commit from {% data variables.location.product_location %}. These snapshots are generated by the [`git archive` command](https://git-scm.com/docs/git-archive) in one of two formats: tarball or zipball. Snapshots don't contain the entire repository history. If you want the entire history, you can clone the repository. For more information, see "[AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository)." + +## Downloading source code archives + +You can download the source code archives in three ways. + +### Downloading source code archives from the repository view + +{% data reusables.repositories.navigate-to-repo %} +1. Above the list of files, click {% octicon "download" aria-label="The download icon" %} **Code**. + + !["Code" button](/assets/images/help/repository/code-button.png) + +1. Click {% octicon "file-zip" aria-label="The ZIP icon" %} **Download ZIP**. + +### Downloading source code archives from a release + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.repositories.releases %} +1. Scroll down to the "Assets" section of the release. +1. To download the source code, click {% octicon "file-zip" aria-label="The ZIP icon" %} **Source code (zip)** or {% octicon "file-zip" aria-label="The ZIP icon" %} **Source code (tar.gz)**. + +### Downloading source code archives from a tag + +{% data reusables.repositories.navigate-to-repo %} +{% data reusables.repositories.releases %} +1. At the top of the Releases page, click **Tags**. +1. To download the source code, click {% octicon "file-zip" aria-label="The ZIP icon" %} **zip** or {% octicon "file-zip" aria-label="The ZIP icon" %} **tar.gz**. + + ![Screenshot of the "Tags" page of a repository. The zip and tar.gz options are outlined in dark orange.](/assets/images/help/repository/tags-download-zip-targz.png) + +## Source code archive URLs + +Source code archives are available at specific URLs for each repository. For example, consider the repository `github/codeql`. There are different URLs for downloading a branch, a tag, or a specific commit ID. + +| Type of archive | Example | URL | +|-----------------|---------|---------| +| Branch | `main` | [https://github.com/github/codeql/archive/refs/**heads/main**.tar.gz](https://github.com/github/codeql/archive/refs/heads/main.tar.gz) | +| Tag | `codeql-cli/latest` | [https://github.com/github/codeql/archive/refs/**tags/codeql-cli/latest**.zip](https://github.com/github/codeql/archive/refs/tags/codeql-cli/latest.zip) | +| Commit | `aef66c4` | [https://github.com/github/codeql/archive/**aef66c462abe817e33aad91d97aa782a1e2ad2c7**.zip](https://github.com/github/codeql/archive/aef66c462abe817e33aad91d97aa782a1e2ad2c7.zip) | + +{% note %} + +**Note**: You can use either `.zip` or `.tar.gz` in the URLs above to request a zipball or tarball respectively. + +{% endnote %} + +## Stability of source code archives + +Source code archives are generated on request, cached for a while, and then deleted. If the same archive is requested again in the future, it'll be regenerated. It's important to understand what guarantees {% data variables.product.company_short %} makes about source code archives. + +* An archive of a commit ID will always have the same file contents whenever it's requested, assuming the commit ID is still in the repository. +* Because branches and tags can move to different commit IDs, future downloads of an archive may have different contents than previously downloaded archives of the same branch or tag. Assuming the branch or tag still points at the same commit ID, it will have the same file contents. +* The exact compression settings used to generate a zipball or tarball may change over time. The extracted contents won't change if the branch or tag doesn't change, but the outer compressed archive may have a different byte layout. {% data variables.product.company_short %} will give at least six months' notice before changing compression settings. + +If you rely on stability of source code archives for reproducibility (ensuring you always get identical files inside the archive), we recommend using the [archives REST API](/rest/repos/contents#download-a-repository-archive-tar) with a commit ID for `:ref`. Using the commit ID ensures you'll always get the same file contents inside the archive and you’ll be immune to repositories rewriting tags or moving branch heads. + +If you rely on stability of archives for security (for example: to ensure you don't attempt to unzip a maliciously-crafted file), we recommend using releases instead of using source downloads. For more information, see "[AUTOTITLE](/repositories/releasing-projects-on-github/about-releases)." + +You can use something like [this third-party {% data variables.product.company_short %} action](https://github.com/softprops/action-gh-release) to create and push these files as part of your release process. The [Release Assets REST API](/rest/releases/assets#get-a-release-asset) can later be used to retrieve them. diff --git a/content/repositories/working-with-files/using-files/index.md b/content/repositories/working-with-files/using-files/index.md index 8fd80fa5d249..a55323280fc3 100644 --- a/content/repositories/working-with-files/using-files/index.md +++ b/content/repositories/working-with-files/using-files/index.md @@ -10,6 +10,7 @@ children: - /navigating-code-on-github - /viewing-a-file - /getting-permanent-links-to-files + - /downloading-source-code-archives - /working-with-non-code-files --- diff --git a/data/reusables/large_files/can-include-lfs-objects-archives.md b/data/reusables/large_files/can-include-lfs-objects-archives.md index baa4cb19177d..215145ff14a1 100644 --- a/data/reusables/large_files/can-include-lfs-objects-archives.md +++ b/data/reusables/large_files/can-include-lfs-objects-archives.md @@ -1,3 +1,3 @@ {% ifversion fpt or ghec %} -You can choose whether {% data variables.large_files.product_name_short %} objects are included in source code archives, such as ZIP files and tarballs, that {% data variables.product.product_name %} creates for your repository. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository)." +You can choose whether {% data variables.large_files.product_name_short %} objects are included in [source code archives](/repositories/working-with-files/using-files/downloading-source-code-archives), such as ZIP files and tarballs, that {% data variables.product.product_name %} creates for your repository. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository)." {% endif %}