mirror-elpa

(To) Mirror Emacs Lisp package archives. Used to create and maintain mirrors under Git repository.

Available mirrors:

• elpa-mirror - GitHub

Note that GitHub is supported out of box as a remote for the mirror. Though you can use mirror-elpa to maintain a local mirror or mirror on any other Git hosting. See Usage section for more information.

The following archives are mirrored:

• GNU ELPA and GNU-devel ELPA
• NonGNU ELPA and NonGNU-devel ELPA
• MELPA and MELPA Stable

Prerequisites

The following software must be installed on your system:

• Git
• Emacs
• rsync

Usage

In order to use mirror-elpa script, you need to prepare configuration file. You can do it manually or use configure script provided by this repository. Example of configuration file:

mirror_path="$XDG_CACHE_HOME/elpa-mirror"
mirror_host="github.com"
mirror_owner="d12frosted"
mirror_repo="elpa-mirror"
access_login="$ACCESS_LOGIN"
access_token="$ACCESS_TOKEN"
commit_name="Your Name"
commit_email="you@example.com"
elpa_clone_path="$XDG_CACHE_HOME/elpa-clone"

function git_config_hook {
  git config commit.gpgsign false
}

Some explanations:

1. mirror_path is location of mirror repository on your disk.
2. mirror_host, mirror_owner and mirror_repo used to build url to your remote mirror repository. Repository URL is build like this:

   mirror_url="https://${access_login}:${access_token}@${mirror_host}/${mirror_owner}/${mirror_repo}.git"
       

3. access_login is user with access to repository.
4. access_token is password/secret/token that is used for authentication. On GitHub you can create access tokens and use them (which is recommended).
5. commit_name and commit_email used as committer information.
6. elpa_clone_path is location of elpa_clone script for Emacs.

The configuration wizard is not maintained, but you can give it a try, as it should help you with token creation.

./configure

GitHub Action

mirror-elpa ships as a composite GitHub Action, so the mirroring can run on a schedule directly from the repository that holds the mirror. Running the cron from the mirror repository itself keeps that repository active (every successful run pushes a snapshot commit), which prevents GitHub from automatically disabling scheduled workflows after 60 days of inactivity. Scheduling it from a rarely-changing tooling repository instead means the schedule keeps getting disabled and has to be re-enabled by hand.

Add a workflow like the following to your mirror repository, for example d12frosted/elpa-mirror at .github/workflows/mirror.yaml (a ready-to-copy version lives in examples/elpa-mirror.yaml):

name: mirror
on:
  schedule:
    - cron: '0 */4 * * *'
  workflow_dispatch:
permissions:
  contents: write
jobs:
  mirror:
    runs-on: ubuntu-latest
    steps:
      - uses: d12frosted/mirror-elpa@master
        with:
          mirror_owner: d12frosted
          mirror_repo: elpa-mirror
          access_token: ${{ secrets.GITHUB_TOKEN }}
          emacs_version: '30.2'

Because the workflow pushes to its own repository, the built-in GITHUB_TOKEN is enough – there is no personal access token to create or rotate. Make sure the job grants contents: write.

Inputs

Input	Required	Default	Description
mirror_owner	yes		Owner of the mirror repository.
mirror_repo	yes		Name of the mirror repository.
access_token	yes		Token used to authenticate the push.
access_login	no	x-access-token	Login paired with access_token.
mirror_host	no	github.com	Git host of the mirror remote.
mirror_repo_branch_name	no	master	Branch to push to.
commit_name	no	github-actions[bot]	Committer name.
commit_email	no	41898282+github-actions[bot]@users.noreply.github.com	Committer email.
commit_gpgsign	no	false	Whether to GPG-sign snapshot commits.
mirror_path	no	temporary directory	Local working path for the mirror checkout.
elpa_clone_path	no	$HOME/.cache/elpa-clone	Local path for the elpa-clone tool.
squash_old_commits	no	false	Whether to squash old commits.
squash_before	no	1 year	Squash commits older than this duration.
emacs_version	no		If set, install this Emacs via d12frosted/setup-emacs.

The runner needs git and rsync available (both are preinstalled on GitHub’s ubuntu-latest images) and an Emacs – either set emacs_version to have the action install one (via =d12frosted/setup-emacs=, which avoids the GitHub API rate limits that make other setups flaky), or provide your own beforehand. Use a stable Emacs version (e.g. 30.2); elpa-clone can fail on dev/snapshot builds. To mirror to another host, set mirror_host accordingly and pass a token for that host (with a matching access_login) via access_token.

Using with CRON

$ ./configure
$ make install

You can also specify how often to sync mirror when running make install (defaults to every 4 hours) and location to resulting configuration file (defaults to $XDG_CONFIG_HOME/mirror-elpa.sh:

$ make install SCHEDULE="0 0 * * *" CONFIG_FILE="~/mirror-elpa.sh"

SCHEDULE can be set to any valid CRON expression.

Credits

• Desmond O. Chang, thanks for elpa-clone.
• Filipe Silva, thanks for keeping this project alive.
• Alyssa Ross, thanks for humans project that inspired me for improving my existing scripts into this project.

Support

If you enjoy this project, you can support its development via GitHub Sponsors or Patreon.