github
Deploy GitHub repositories into site directories, keep them in sync, and package them as installable scripts
- Command:
/go/github - Category: Deployment
- Required option: None for sync mode.
<url>and<directory>for download mode. - Output: Plain text. Script mode prints PHP snippets.
- Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/github does three different jobs, chosen by the arguments you pass:
| Mode | Command | What it does |
|---|---|---|
| Download | /go/github <url> <directory> <sync> |
Clones a public repository into a site directory and registers it. |
| Sync | /go/github |
Updates every registered repository that has changed on GitHub. |
| Script | /go/github <url> <category> --script |
Packages a repository as a .tar.gz and prints the database entry for the GoAdmio script catalog. |
Download mode:
- clones the repository (latest commit only) into the directory
- reports the date and email of the latest commit
- fixes file permissions in the background
- saves the repository in the GitHub database so it can be synced later
- sends a notification email
Only public repositories are supported. The command calls GitHub's API without authentication.
Quick start
# Download a repository into an empty site directory and keep it synced
/go/github https://github.com/justmarkham/pandas-videos /home/example.com/www 1
# Update all repositories registered for sync (run this from cron)
/go/github
Syntax
# Download a repository
/go/github <url> <directory> <sync> [--progress]
# Sync all registered repositories
/go/github
# Package a repository for the script catalog
/go/github <url> <category> --script
The mode is picked in this order:
- No arguments: sync mode.
--scriptanywhere in the arguments: script mode.- Anything else: download mode.
[!IMPORTANT] The third argument is always read as
<sync>. If you pass--progressthere, it is saved as the sync value. Always give<sync>first, then--progress.
Options
Download mode
| Argument | Required | Default | Notes |
|---|---|---|---|
<url> |
Yes | — | Format https://github.com/<owner>/<repo>. No trailing slash and no .git suffix. |
<directory> |
Yes | — | Must already exist and be empty. Use the form /home/<domain>/www, because the domain is read from the third path segment. |
<sync> |
No | Empty (not synced) | Pass 1 to include the repository in sync mode. Any other value means no sync. |
--progress |
No | Off | Prints progress markers (15 and 100) for the panel's progress bar. |
Script mode
| Argument | Required | Default | Notes |
|---|---|---|---|
<url> |
Yes | — | Format https://github.com/<owner>/<repo>. |
<category> |
No | Empty | Written to the $Category line in script.txt. |
--script |
Yes | — | Selects script mode. |
Sync mode
None. Sync mode runs only when /go/github has no arguments.
Output
Download mode
Last Updated: 2026-11-18T10:22:31Z
Email: 12345+user@users.noreply.github.com
Github files (pandas-videos) downloaded successfully
Last Updated and Email come from the latest commit on GitHub. With --progress, the progress lines Download in progress, Please wait... and 15 are printed first, then a completion message and 100.
Sync mode
For each repository that has changed, one line:
Syncing https://github.com/justmarkham/pandas-videos -> /home/example.com/www
Nothing is printed for repositories that are up to date.
Script mode
The command prints the following lines and appends them to script.txt in the current directory. The printed copy has an empty $Category. The copy in script.txt uses the category you passed.
$ScriptName="owner/repo";
$ScriptFile="owner-repo";
$ScriptLanguage="English";
$ScriptVersion="1.2.3";
$Category="";
$Description="Repository description";
$URL="https://script.goadmio.com/owner-repo.tar.gz";
$GithubURL="https://github.com/owner/repo";
$Sql = "INSERT INTO Script (ScriptName,ScriptFile,ScriptLanguage,ScriptVersion,Category,Description,URL) VALUES ('$ScriptName','$ScriptFile','$ScriptLanguage','$ScriptVersion','$Category','$Description','$URL')";
SQL($Sql);
The archive owner-repo.tar.gz (lowercase) is created in the current directory.
Messages and exit status
| Outcome | What you get |
|---|---|
| Download completed | The three lines above. Exit status 0. |
| Directory missing | Directory <directory> not Exists. Nothing is changed. |
| Archive already exists (script mode) | File <name>.tar.gz Already Exists. Nothing is changed. |
| Sync or script mode finished | Exit status 1, even on success. Don't use the exit status to detect errors. |
Every run is logged to /var/log/go/github.log with a timestamp and the arguments used.
Examples
# Download into the site's www folder and keep it synced
/go/github https://github.com/justmarkham/pandas-videos /home/example.com/www 1
# Download once, without sync, with progress markers
/go/github https://github.com/justmarkham/pandas-videos /home/example.com/www 0 --progress
# Sync all registered repositories
/go/github
# Package a repository for the script catalog, with a category
/go/github https://github.com/owner/repo "CMS" --script
# Run the sync every hour from cron
0 * * * * /go/github >/dev/null 2>&1
[!NOTE] Without a token, GitHub allows only 60 API requests per hour per IP address. Each registered repository uses two requests per sync run, so keep the schedule infrequent if you sync many repositories.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Directory <directory> not Exists. |
The path is wrong or the account doesn't exist yet. | Create the account with create, or check the path. |
destination path '.' already exists and is not an empty directory |
The directory already has files. | Empty the directory first. The script doesn't stop on this error and still prints "downloaded successfully", so check the directory yourself. |
| Nothing happens in download mode | The URL ends with /. |
Pass the URL without a trailing slash. |
| API errors, or "Last Updated" is empty | Wrong URL format (for example .git at the end), or the GitHub API rate limit was reached. |
Use https://github.com/<owner>/<repo>, or wait an hour. |
| Repository is re-synced on every run | The API call failed, so the stored date never matches. | Check the URL and the rate limit. |
| Repository is never synced | <sync> wasn't 1, or /go/github isn't scheduled. |
Register it again with 1, and add the cron job. |
| Repository is synced twice | Download mode ran more than once for the same repository, which adds a new database row each time. | Remove the duplicate row from the Github table in /var/lib/sqlite/github.db. |
| Synced files are owned by root | Sync mode doesn't fix ownership. | Run fix after syncing. |
| Clone asks for a username and password | The repository is private. | Only public repositories are supported. |
File <name>.tar.gz Already Exists. |
A previous archive is in the current directory. | Delete the old archive and run again. |
Empty $ScriptVersion or $Description |
The repository has no releases, or GitHub's page layout changed. | Fill in the values by hand in script.txt. |
Details
Download mode
- Checks that
<directory>exists. - Reads the domain from the directory path and looks up the account's username in
site.db. - Deletes
.git,.gitignore, and.gitattributesin the directory. - Clones the repository into the directory with
git clone --depth 1. - Reads the latest commit date and email from the GitHub API.
- Starts
fixin a detachedscreensession. - Adds a row to the
Githubtable with the URL, directory, commit date, username, and sync value. - Sends the notification email twice with
/go/sendmail. Both messages are identical.
Sync mode
flowchart TD
A["/go/github (no arguments)"] --> B["Read repositories with Sync = 1"]
B --> C["Latest commit date from GitHub API"]
C --> D{"Same as stored date?"}
D -- "Yes" --> E["Skip"]
D -- "No" --> F["git clone into /usr/local/goadmio/tmp"]
F --> G["rsync into the site directory"]
G --> H["Delete the temporary clone"]
H --> I["Save the new commit date"]
Sync mode does a full clone (not --depth 1) and copies it with rsync without --delete. Files you removed from the repository stay in the site directory.
Script mode
- Clones the repository into a folder named
<owner>-<repo>(lowercase). - Compresses it to
<owner>-<repo>.tar.gzand deletes the folder. - Downloads the repository's GitHub page and extracts the description and the latest release tag.
- Prints the catalog entry and appends it to
script.txt.
The description and version are scraped from GitHub's HTML, so they can come out empty or incomplete. The release tag is only matched when it uses lowercase letters, digits, and dots.
Data and requirements
| Item | Used for |
|---|---|
/var/lib/sqlite/github.db |
The Github table: GithubID, URL, Directory, Date, Username, Sync. |
/var/lib/sqlite/site.db |
Looking up the account's username from its domain. |
/usr/local/goadmio/tmp |
Temporary clones during sync. |
/var/log/go/github.log |
The command log. |
git, curl, jq, rsync, sqlite3, screen |
All modes. |
wget, tar |
Script mode. |
fix, /go/sendmail |
Download mode. |
Security notes
- The clone leaves a
.gitfolder in the site directory, and sync copies it too. Make sure the web server doesn't serve it, or delete it. - The latest committer's email address is printed in the output.
- Run the command as root or an administrator only. It uses
sudoand writes to system databases.
See also
| Command | Description |
|---|---|
gdown |
Download files from Google Drive |
fix |
Fix GoAdmio file and folder permissions |
create |
Create a GoAdmio account from the command line |
cron |
Set up main cron jobs in GoAdmio |
vendor |
Install or update Composer vendor dependencies |
composer |
Install Composer (PHP dependency manager) |