Awesome
<h1> <p align="center"> UNMAINTAINED: External repo/wiki sync action </p> </h1> <div align="center"> This repository provides a GitHub action to push files/binaries to <strong>external repositories</strong>. Per default, the action uses the wiki of the current repo, but you can specify other repos as well.
- When to use this action
- When not to use the action
- Set-Up
- Inputs and Output
- Examples
- How it works
- Security concerns/Implications
- License
- Contributing
- Contact
STATUS: UNMAINTAINED
As I am no longer using the project, I have changed the status to UNMAINTAINED
and archived the repository.
Feel free to fork the project!
Currently, the majority of the maintainence work would be updating GitHub action dependencies and moving the tutorial
and the internal CI pipeline to use the new fine-grained personal access tokens.
The fish shell code is a thin wrapper around git
and rsync
.
It should be fairly easy to update the code or to move it to an easier scripting language, such as nushell.
When to use this action
You can use this action in two ways:
- Automatically push to the repo's wiki (default setting)
- 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
-
Enable your repository's wikis feature
-
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.
-
Add the first wiki page
After enabling the wiki, go to the Wiki tab. If not already done, create the first wiki page.
-
-
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!
-
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. :tada:
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 usermail
: 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 isAction 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! Usedry-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. :)