# Git Download Updater - Setup Documentation When you release a new version of a plugin or theme, the usual process means downloading a zip from your repository, renaming the folder, and re-uploading it to your store. The [Git Download Updater](https://easydigitaldownloads.com/downloads/git-download-updater/) feature automates this process for code hosted on GitHub or Bitbucket. It pulls directly from a version tag or release, handles file naming, and keeps your store's download files in sync with your repository. - [Requirements](#requirements) - [Connecting to GitHub](#connecting-to-github) - [Step 1: Create a GitHub OAuth App](#step-1-create-a-github-oauth-app) - [Step 2: Connect GitHub in EDD Settings](#step-2-connect-github-in-edd-settings) - [Connecting to Bitbucket](#connecting-to-bitbucket) - [Step 1: Create a Bitbucket API Token](#step-1-create-a-bitbucket-api-token) - [Step 2: Connect Bitbucket in EDD Settings](#step-2-connect-bitbucket-in-edd-settings) - [Configuring a Download to Use Git Updater](#configuring-a-download-to-use-git-updater) - [Setting the Download File](#setting-the-download-file) - [Plugin Folder Name](#plugin-folder-name) - [Selecting a GitHub Release Asset](#selecting-a-github-release-asset) - [Version Rollback](#version-rollback) - [Performing a Routine Update](#performing-a-routine-update) - [Key Terms](#key-terms) - [Notes](#notes) - [Troubleshooting](#troubleshooting) --- Requirements ------------ **Note**: Git Download Updater requires an Easy Digital Downloads [Professional or All Access Pass](https://easydigitaldownloads.com/pricing/). Before activating Git Download Updater, confirm that your hosting environment has the **PHP ZipArchive** extension enabled. This extension is required for the feature to function. If you see an error immediately after activation, contact your hosting provider and ask them to enable ZipArchive on your account. You can install and activate the Git Download Updater feature on your EDD site under **Downloads** » **Extensions** Connecting to GitHub -------------------- GitHub connections use OAuth, which requires a one-time setup in your GitHub account. You'll create a GitHub OAuth App, paste its credentials into your EDD settings, and then authorize the connection. ### Step 1: Create a GitHub OAuth App - Go to **Downloads** » **Settings** » **Extensions** » **Git Updater**. - Under **GitHub Status**, click the **Create an application** link. This opens GitHub's OAuth App creation page in your GitHub account. ![The Git Updater settings screen in EDD for the Git Download Updater feature.](https://easydigitaldownloads.com/wp-content/uploads/2022/01/edd-git-updater-settings-screen.png)- Fill in the application details. Set both the **Main URL** (Homepage URL) and **Callback URL** (Authorization callback URL) to your site's URL (for example, `https://yoursite.com`). - Save the app. GitHub will display a **Client ID** and allow you to generate a **Client Secret**. Copy both values. ![GitHub Client ID and Client Secret values.](https://easydigitaldownloads.com/wp-content/uploads/2022/01/gituhb-application-client-id-secret-800x376.png)### Step 2: Connect GitHub in EDD Settings - Return to **Downloads** » **Settings** » **Extensions** » **Git Updater**. - Paste your **Client ID** and **Client Secret** into their respective fields. - Select **Save Changes**. - Click **Authorize with GitHub**. You'll be redirected to GitHub to approve the connection. After approving, you'll return to your EDD settings with GitHub connected. ![GitHub Status shown as Connected in Easy Digital Downloads Git Updater settings.](https://easydigitaldownloads.com/wp-content/uploads/2022/01/edd-git-updater-status-connected.png)--- Connecting to Bitbucket ----------------------- Bitbucket connections use an API token tied to your Atlassian account. You'll create the token at **[id.atlassian.com](https://id.atlassian.com)** under **Security** » **API tokens**, then enter your email address and token in your EDD settings. ### Step 1: Create a Bitbucket API Token 1. Go to **Downloads** » **Settings** » **Extensions** » **Git Updater**. 2. Under **Bitbucket Status**, click **create an API token**. 3. Give it a descriptive name (for example, "EDD Git Updater"). 4. Under **App**, select **Bitbucket**. 5. Enable only the following scopes: `read:workspace:bitbucket` (View workspaces) and `read:repository:bitbucket` (View repositories). 6. Save the token and copy it. **This value is only shown once.** ![The Bitbucket status, Atlassian account email, and API token settings in Easy Digital Downloads.](https://easydigitaldownloads.com/wp-content/uploads/2022/01/edd-git-updater-settings-bitbucket-status-800x343.png)### Step 2: Connect Bitbucket in EDD Settings 1. Go back to **Downloads** » **Settings** » **Extensions** » **Git Updater**. 2. Enter the email address you use to log in to Atlassian in the **Atlassian Account Email** field. 3. Paste your token into the **Bitbucket API Token** field. 4. Click **Save Changes**. ⚙️ More details can be found in the Bitbucket [documentation](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/#Create-an-app-password). --- Configuring a Download to Use Git Updater ----------------------------------------- ### Setting the Download File 1. Open a download in the EDD editor and locate the **Download Details** » **Files** section. 2. Select the option to **Fetch download from a git repository**. New fields will appear. 3. Under the **Git Repository**, search for your repository name and select it from the dropdown. 4. Select the version tag you want to serve to customers. (**Note**: The Version Tag used in Git Updater is required to be a native git tag. It does not parse versions from your readme file. To learn more about using the tag feature in git, you can [visit this guide](https://git-scm.com/book/en/v2/Git-Basics-Tagging).) 5. Click **Fetch Now**. The button changes to **Fetched** when complete. ![Configuring a download product file in EDD to use Git Updater](https://easydigitaldownloads.com/wp-content/uploads/2022/01/edd-download-files-fetch-github-repository-800x398.png)### Plugin Folder Name The **Plugin Folder Name** field controls the folder name inside the zip file that customers download. This value must exactly match the installed folder name of your plugin or theme on the customer's site. **Important:** If the Plugin Folder Name doesn't match the installed folder name, customer updates will fail silently. WordPress won't throw a visible error, but the update won't apply correctly. Double-check this value before saving. ### <a></a>Selecting a GitHub Release Asset If you publish pre-built release files on GitHub (for example, a packaged and compiled zip), you can serve that file directly instead of using the raw source archive. After selecting a version tag, a **Release Asset** dropdown will appear. Choose the file you want to serve to customers. This is useful when your repository's source code requires a build step before it can be distributed. ### <a></a>Version Rollback The version tag dropdown shows all available tags in your repository, not just the latest. To serve an older version, select an earlier tag from the dropdown and click **Fetch Now**. This is useful for quickly reverting a release if a new version has an issue. --- Performing a Routine Update --------------------------- When you're ready to release a new version, the process takes four steps: 1. Open the download in your EDD store. 2. In the **Download Details** » **Files** metabox, change the version tag to the new version. 3. Click **Fetch Now**. 4. Save the download. --- Key Terms --------- **Tag:** A label placed on a specific point in your code history, typically marking a release version (for example, `v1.2.0`). Git Updater uses tags to know which version of your code to fetch and serve to customers. **OAuth:** A secure authorization method that lets your site connect to your GitHub account without storing your password. When you click **Authorize with GitHub**, you're granting access through OAuth. **API Token:** A code that acts like a limited-access password, giving your site permission to read your Bitbucket account. Unlike your actual password, an API token can be revoked at any time without changing your login credentials. Notes ----- - **Variable pricing:** Variable pricing tiers are supported. Each file row in the Files metabox can be assigned to a different pricing tier. - **Repository cache:** Repository lists are cached. If a newly connected repository doesn't appear in the dropdown immediately, save the settings page to refresh the cache. - **Changelog updates:** Automatic changelog updates require Software Licensing to be installed and active on your site. See the [Software Licensing documentation](https://easydigitaldownloads.com/docs/software-licensing-usage-instructions/) for setup instructions. --- Troubleshooting --------------- **Plugin shows an error after activation** The PHP ZipArchive extension is likely missing from your hosting environment. Contact your hosting provider and ask them to enable ZipArchive. **Repository dropdown is empty** Your credentials may be incorrect or your token may be missing the required permissions. Double-check the fields in **Downloads** » **Settings** » **Extensions** » **Git Updater** and save the settings page to refresh the repository cache. **Fetch Now times out** Your server's maximum execution time may be too low for larger repositories. Contact your hosting provider to increase the limit, or switch to serving a pre-built GitHub release asset instead of fetching from the raw source. **Customers aren't receiving updates** The Plugin Folder Name field is likely set incorrectly. It must exactly match the installed folder name of your plugin or theme. Correct the value and click **Fetch Now** again to re-fetch with the correct folder name. **Excluding files from the exported zip** Use a `.gitattributes` file in your repository to control which files are excluded during export. See EDD's own [.gitattributes file](https://github.com/easydigitaldownloads/easy-digital-downloads/blob/master/.gitattributes) as a reference example. **Free and paid version conflicts** If your free and paid versions share the same plugin slug, either rename the slug in your paid version or add `wp_override` as a parameter when instantiating the `EDD_SL_Plugin_Updater` class (requires v1.6.4 or later).