External repo/wiki sync action

This repository provides a GitHub action to push files/binaries to external repositories. Per default, the action uses the wiki of the current repo, but you can specify other repos as well.

• When to use this action
  • Automatically pushing to the repo's wiki
  • Updating and pushing to a different repository
• When not to use the action
• Set-Up
• Inputs and Output
  • Inputs
  • Output
• Examples
  • Using defaults
  • Including different extensions
  • Excluding different extensions
  • Including and excluding different extensions
• How it works
• Security concerns/Implications
• License
• Contributing
• Contact

When to use this action

You can use this action in two ways:

1. Automatically push to the repo's wiki (default setting)
2. Update and push a different repository

Automatically pushing to the repo's wiki

This action helps to push files and binaries to the wiki of the current repository. Instead of only pushing .md-files, which could be displayed in the GitHub wiki, the wiki can also be re-used to serve as a hosting solution for automatically generated files/binaries.

This is useful for repositories that need/want to display the newest graphical changes or example images without increasing the size of the repository. Or simply keep the wiki up to date.

Updating and pushing to a different repository

One can also specify a separate target repository instead of pushing specified files/binaries to the wiki of the current repository. One can use this option if a separate developer/nightly repository and a stable/production repository exists..

When not to use the action

If the goal is to modify and push to the existing repository, a different action should be used, for example, git-auto-commit-action

Set-Up

0. Enable your repository's wikis feature

   1. If you want to push to the wiki, you have to initialize the wiki first.

      Go to the Settings of the repository and under Options enable the Wiki Feature.

      

   2. Add the first wiki page

      After enabling the wiki, go to the Wiki tab. If not already done, create the first wiki page.

      

1. A Personal Access Token has to be used. Go to the Personal access token page and click on Generate new token.

   Location: User icon -> Settings -> Developer settings -> Personal access tokens

   Give it a name and enable all of the entries under repo.

   

   Now click on Generate token and copy the token to your clipboard. The token will not be accessible again!

2. Finally, paste the personal access token from your clipboard to the GitHub secrets of your project.

   Location: under the repo Settings -> Secrets -> New secret

   I would recommend naming it GH_ACCESS_TOKEN to have the same name for the variable and the action call.

   

Now you are ready to use the action. 🎉

Inputs and Output

Inputs

As described in the set-up description, before you use the action, add a GitHub access token with repository rights to the repository secrets. The remaining arguments of the script are the following:

• source-directory: The source directory which is the root for the patterns (Required)
• repository: Set which repository should be the target for the sync process. By default, the wiki of the current repository is used.
• user: Set the user name configuration for the push. The default name is the triggering user
• mail: Set the email configuration for the push. Default mail is GitHub user @users.noreply.github.com
• commit-message: Set the commit-message for the push. Default is Action Bot is pushing.
• branch: Set which branch should be checked out. It never creates a new one. Default is master.
• dry-run: Doesn't touch repository. The command will run in an empty folder. This shows what files will would be synced with the repo without touching it. Default is false.
• delete-missing: Delete all files in the repo that are not present in the source-directory. Please be careful when using this option! Use dry-run to see which files would be synced first. Default is false

Note: All commands and patterns are case-sensitive! To include *.JPG *.jpg, please specify all desired variations.

Output

This action outputs the folder structure of the defined repository after syncing. The output is mainly used for testing.

• sync_result: Output variable name

Examples

A couple of different examples on how to use the action:

Using defaults

By default all files are synced from the docs folder to the wiki of the current repository:

  jobs:
    sync_docs:
      name: Sync docs
      runs-on: ubuntu-latest
      steps:
        - name: Checkout current version
          uses: actions/checkout@v2
        - name: Create files to sync
          run: |
            mkdir docs/
            touch docs/hello.md
        - name: Sync with local action
          uses: kai-tub/external-repo-sync-action@v1
          with:
            source-directory: "./docs"
          env:
            GH_ACCESS_TOKEN: ${{ secrets.GH_ACCESS_TOKEN }}

With the resulting files in docs:

  .
  └── hello.md

Including different extensions

To include multiple patterns, please use spaces to separate them and place them in quotes. The patterns are case-sensitive, and if include is used, all other files are automatically excluded. (This is not the default behavior of rsync)

With the following files in docs:

  .
  ├── folder_a
  │   ├── cat.jpg
  │   ├── cat_transparent.png
  │   └── dog.JPG
  ├── folder_b
  │   ├── README.md
  │   ├── result.pdf
  │   └── result.tmp.pdf
  ├── hello.md
  └── hello.png

And the following configuration:

  # Checkout repo and add files if necessary
  - name: Sync with include
    uses: kai-tub/external-repo-sync-action@v1
    with:
      source-directory: "./docs"
      include-patterns: "*.md *.jpg"
    env:
      GH_ACCESS_TOKEN: ${{ secrets.GH_ACCESS_TOKEN }}

With the resulting files in docs:

  .
  ├── folder_a
  │   └── cat.jpg
  ├── folder_b
  │   └── README.md
  └── hello.md

Excluding different extensions

To exclude multiple patterns, please use spaces to separate them and place them in quotes. The patterns are case-sensitive.

With the following files in docs:

  .
  ├── folder_a
  │   ├── cat.jpg
  │   ├── cat_transparent.png
  │   └── dog.JPG
  ├── folder_b
  │   ├── README.md
  │   ├── result.pdf
  │   └── result.tmp.pdf
  ├── hello.md
  └── hello.png

And the following configuration:

  # Checkout repo and add files if necessary
  - name: Sync with exclude
    uses: kai-tub/external-repo-sync-action@v1
    with:
      source-directory: "./docs"
      exclude-patterns: "*.md *.jpg"
    env:
      GH_ACCESS_TOKEN: ${{ secrets.GH_ACCESS_TOKEN }}

With the resulting files in docs:

  .
  ├── folder_a
  │   ├── cat_transparent.png
  │   └── dog.JPG
  ├── folder_b
  │   ├── result.pdf
  │   └── result.tmp.pdf
  └── hello.png

Including and excluding different extensions

To include/exclude multiple patterns, please use spaces to separate them and place them in quotes. The patterns are case-sensitive.

With the following files in docs:

  .
  ├── folder_a
  │   ├── cat.jpg
  │   ├── cat_transparent.png
  │   └── dog.JPG
  ├── folder_b
  │   ├── README.md
  │   ├── result.pdf
  │   └── result.tmp.pdf
  ├── hello.md
  └── hello.png

And the following configuration:

  # Checkout repo and add files if necessary
  - name: Sync with include and exclude
    uses: kai-tub/external-repo-sync-action@v1
    with:
      source-directory: "./docs"
      include-patterns: "*.pdf *.png"
      exclude-patterns: "*.tmp.pdf"
    env:
      GH_ACCESS_TOKEN: ${{ secrets.GH_ACCESS_TOKEN }}

With the resulting files in docs:

  .
  ├── folder_a
  │   └── cat_transparent.png
  ├── folder_b
  │   └── result.pdf
  └── hello.png

How it works

The action is an rsync and git wrapper with some sensible settings. The action only clones the specified branch with a depth of 1 for better performance. As an rsync wrapper, one limitation is the missing support for case-insensitive patterns, but I decided not to add the feature, as NTFS filesystems are case insensitive.

Security concerns/Implications

As a security measure, forked repositories cannot trigger workflows that use your GitHub access token. See GitHub help

Consequently, it is not straightforward to automatically push to the other repo or the wiki when merging branches from forks. I suggest triggering on deploy events to a PR or, for a very hacky solution, on a manual trigger, described in dev.to

License

This software is released under the GNU GPL v3.0 License.

Contributing

Please see the contribution guidelines for more information.

As always, PRs are welcome. :)

Contact

If you have any comments, issues, or suggestions, please open an issue on GitHub. I try to help as much as I can. :)