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 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

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.

• 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.

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.

---

Connecting to Bitbucket

Bitbucket connections use an API token tied to your Atlassian account. You’ll create the token at 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.

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.

---

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.)
5. Click Fetch Now. The button changes to Fetched when complete.

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.

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.

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 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 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).