Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kai-tub/external-repo-sync-action
GitHub action to automatically sync and publish changes to external repositories, like the wiki for example.
https://github.com/kai-tub/external-repo-sync-action
ci github-action sync synchronization wiki wiki-action
Last synced: 24 days ago
JSON representation
GitHub action to automatically sync and publish changes to external repositories, like the wiki for example.
- Host: GitHub
- URL: https://github.com/kai-tub/external-repo-sync-action
- Owner: kai-tub
- License: gpl-3.0
- Created: 2020-05-20T07:42:47.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2023-10-27T21:34:36.000Z (7 months ago)
- Last Synced: 2024-05-06T15:01:42.735Z (29 days ago)
- Topics: ci, github-action, sync, synchronization, wiki, wiki-action
- Language: Shell
- Homepage: https://github.com/kai-tub/external-repo-sync-action
- Size: 51.8 KB
- Stars: 8
- Watchers: 3
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Lists
- awesome-workflows - Sync Defined Files/Binaries to Wiki or External Repositories
- awesome-actions - Sync Defined Files/Binaries to Wiki or External Repositories
- awesome-actions - Sync Defined Files/Binaries to Wiki or External Repositories
- fucking-awesome-actions - Sync Defined Files/Binaries to Wiki or External Repositories
- awesome-actions-fork - Sync Defined Files/Binaries to Wiki or External Repositories
- awesome-actions - Sync Defined Files/Binaries to Wiki or External Repositories
README
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.
[](https://github.com/kai-tub/external-repo-sync-action/releases)
[](https://github.com/kai-tub/external-repo-sync-action/blob/master/LICENSE)
[](CODE_OF_CONDUCT.md)
[](https://github.com/intuit/auto)
- [When to use this action](#when-to-use-this-action)
- [Automatically pushing to the repo's wiki](#automatically-pushing-to-the-repos-wiki)
- [Updating and pushing to a different repository](#updating-and-pushing-to-a-different-repository)
- [When not to use the action](#when-not-to-use-the-action)
- [Set-Up](#set-up)
- [Inputs and Output](#inputs-and-output)
- [Inputs](#inputs)
- [Output](#output)
- [Examples](#examples)
- [Using defaults](#using-defaults)
- [Including different extensions](#including-different-extensions)
- [Excluding different extensions](#excluding-different-extensions)
- [Including and excluding different extensions](#including-and-excluding-different-extensions)
- [How it works](#how-it-works)
- [Security concerns/Implications](#security-concernsimplications)
- [License](#license)
- [Contributing](#contributing)
- [Contact](#contact)
# When to use this action
You can use this action in two ways:
1. [Automatically push to the repo's wiki](#automatically-pushing-to-the-repos-wiki) (default setting)
2. [Update and push a different repository](#updating-and-pushing-to-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](https://github.com/stefanzweifel/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*.
1. 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](https://github.com/settings/tokens) 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. :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 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:
```yml
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:
```yml
# 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:
```yml
# 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:
```yml
# 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](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)
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](https://dev.to/s_abderemane/manual-trigger-with-github-actions-279e)
# License
This software is released under the GNU GPL v3.0
[License](LICENSE).
# Contributing
Please see the [contribution guidelines](CONTRIBUTING.md) 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. :)