Waystation

Waystation is a GitHub Action that makes it easy to archive your repository’s GitHub Pages site automatically in the Internet Archive’s Wayback Machine.

Introduction

Many projects use GitHub Pages for documentation and other purposes. GitHub Pages are wonderful, but they are not archived. To help ensure long-term access to your GitHub Pages, you may want to preserve them in the Internet Archive’s Wayback Machine. That’s the purpose of this GitHub Action.

How does Waystation work?

Waystation (a loose acronym of Wayback site archiving automation) sends your project’s GitHub Pages URL to the Wayback Machine. It’s intended to be triggered on software releases in your repository and uses the Wayback Machine GitHub Action to send your repository’s configured GitHub Pages URL to the Wayback Machine, thereby ensuring that the latest copy of your site is archived. You can change the trigger condition if needed.

Why would you want to bother with this?

GitHub is incredibly popular today, but the content is not guaranteed to be permanent; moreover, GitHub has in the past changed the URLs and policies surrounding GitHub Pages—and may do so again in the future. The Wayback Machine is a free digital archive of the World Wide Web founded by the Internet Archive. Web pages saved in the Wayback Machine continue to exist even after the original project repository changes or is removed from the web, and the archived pages can be searched for, shared, and linked to normally. You can also view previous versions of a site if they were archived.

Installation

To use Waystation, you need to create a GitHub Actions workflow file in your repository. Follow these simple steps.

Add the workflow file to your repository

1. In the main branch of your repository, create a .github/workflows directory if this directory does not already exist.

2. In the .github/workflows directory, create a file named archive-github-pages.yml.

3. Copy and paste the following content into the file:

   # GitHub Actions workflow for Waystation version 1.8.0.
   # Available as the file "sample-workflow.yml" from the software
   # repository at https://github.com/caltechlibrary/waystation
   
   name: Archive GitHub Pages
   run-name: Archive GitHub Pages in the Wayback Machine
   
   on:
     release:
       types: [published]
     workflow_dispatch:
       inputs:
         dry_run:
           description: Run without actually sending URLs
           type: boolean
   
   jobs:
     run-waystation:
       name: Run Waystation
       runs-on: ubuntu-latest
       steps:
         - uses: caltechlibrary/waystation@v1.8
           with:
             dry_run: ${{github.event.inputs.dry_run || false}}
   

4. Save the file, add it to your git repository, and commit the changes.

5. (If you did the steps above outside of GitHub) Push your repository changes to GitHub.

Test the workflow

Once you have created the workflow file and pushed it to GitHub, it’s wise to do a dry run, in order to test that things work as expected.

1. Go to the Actions tab in your repository and click on the workflow named “Archive GitHub Pages” in the sidebar on the left

   

2. In the page shown by GitHub next, click the Run workflow button in the right-hand side of the blue strip

   

3. In the pull-down, click the checkbox for “Run without actually sending URLs”

   

4. Click the green Run workflow button near the bottom

5. Refresh the web page and a new line will be shown named after your workflow file

   

6. Click the title of that workflow, to make GitHub show the progress and results of running Waystation

Usage

Once installed, the sample workflow will run automatically the next time you publish a release on GitHub. The trigger condition that causes Waystation to run automatically is determined by the on statement in your archive-github-pages.yml workflow file. The examples shown here use on: release to trigger when a release is published, but you can use other trigger events defined by GitHub if you wish.

Several optional parameters control the behavior of Waystation; they are described below.

dry_run (default: false)

Setting the parameter dry_run to true will cause the action to execute without sending the URL to the Wayback Machine. This is mainly useful for testing, especially if you want to try different trigger conditions.

The sample workflow file (shown above) includes a dry_run parameter checkbox when invoked manually. You can use that to set the value on an individual per-run basis. To change the default value (for example, when experimenting with different trigger conditions), you can do so by changing the false to true in the last line of the sample workflow. That is, change the last line from

dry_run: ${{github.event.inputs.dry_run || false}}

to

dry_run: ${{github.event.inputs.dry_run || true}}

debug (default: false)

Passing the parameter debug with a value of true will cause Waystation to print the values of the input variables and the GitHub context at run time. This is useful for debugging the workflow. To set the debug parameter, add it as part of the with: block in the workflow file. For example:

    ...
      - uses: caltechlibrary/waystation@main
        with:
          dry_run: ${{github.event.inputs.dry_run || false}}
          debug: true
    ...

save_outlinks (default: true)

This corresponds to the parameter saveOutlinks in the Wayback Machine GitHub Action. A value of true will make the action tell the Wayback Machine to archive external pages that are linked to from your GitHub Pages. The default in Waystation is true because Waystation’s author finds this useful in producing a more complete archive of a GitHub Pages site. To set the save_outlinks parameter, add it as part of the with: block in the workflow file. For example:

    ...
      - uses: caltechlibrary/waystation@main
        with:
          dry_run: ${{github.event.inputs.dry_run || false}}
          save_outlinks: true
    ...

save_screenshot (default: true)

This corresponds to the parameter saveScreenshot in the Wayback Machine GitHub Action. A value of true will make the action tell the Wayback Machine to save a screenshot of the page located at the GitHub Pages URL. The default in Waystation is true because Waystation’s author finds this useful in producing a more complete archive of a GitHub Pages site. To set the save_screenshot parameter, add it as part of the with: block in the workflow file. For example:

    ...
      - uses: caltechlibrary/waystation@main
        with:
          dry_run: ${{github.event.inputs.dry_run || false}}
          save_screenshot: true
    ...

Getting help

If you find an issue, please submit it in the GitHub issue tracker for this repository.

Contributing

Your help and participation in enhancing Waystation is welcome! Please visit the guidelines for contributing for some tips on getting started.

License

Software produced by the Caltech Library is Copyright © 2022–2024 California Institute of Technology. This software is freely distributed under a modified BSD 3-clause license. Please see the LICENSE file for more information.

Acknowledgments

This work was funded by the California Institute of Technology Library.

Waystation makes use of the excellent Wayback Machine GitHub Action by Jamie Magee.