Skip to content

Commit 481c522

Browse files
varunsridharanvarunsridharan
committed
Updated README.md
1 parent 18a9870 commit 481c522

File tree

1 file changed

+129
-17
lines changed

1 file changed

+129
-17
lines changed

‎README.md‎

Lines changed: 129 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,21 @@ _This Github Action can come in handy when you have lot of projects like i do._
1010
_where in some case certain projects users action workflow which are common across projects._
1111
_Example : [Project 1][project1] & [Project 2][project2] it can be pain to keep all the workflow updated with Github Action's Module's version._
1212

13+
This also isn't limited to Github Action yaml files - another use case could be keeping the `.editorconfig`, `LICENSE`, `tsconfig.json`, `tslint.json`, `.gitignore`, `azure-pieplines.yml`, etc. in sync across all your repositories.
14+
1315
>_Here where this action comes in and reduces your stress 😉 it can update all your repository actions file based on the config provided_
1416
1517
## ⚙️ Configuration
1618

17-
| **Argument** | Description |
18-
| --- | :---: |
19-
| `github_token` | **Required** Token to use to get repos and write secrets. `${{secrets.GITHUB_TOKEN}}` will not work. instead **Personal Access Token Required*** |
20-
| `repositories` | **Required** New line deliminated regex expressions to select repositories. Repositires are limited to those in whcich the token user is an owner or collaborator. |
21-
| `workflow_files` | **Required** New line deliminated regex expressions. workflow files to be copied to provided repositores |
22-
| `dry_run` | Run everything except for nothing will be pushed. |
19+
| **Argument** | Defaults | Description |
20+
| --- | :---: | :---: |
21+
| `GITHUB_TOKEN` | - | **Required** Token to use to get repos and write secrets. `${{secrets.GITHUB_TOKEN}}` will not work. instead **Personal Access Token Required*** |
22+
| `REPOSITORIES` | - | **Required** New line deliminated regex expressions to select repositories. Repositires are limited to those in whcich the token user is an owner or collaborator. |
23+
| `WORKFLOW_FILES` | - | **Required** New line deliminated regex expressions. workflow files to be copied to provided repositores |
24+
| `DRY_RUN` | ***false*** | Run everything except for nothing will be pushed. |
25+
| `WORKFLOW_FILES_DIR` | ***workflows*** | Local Path Where Common Workflow Files Are Located ***Eg : `workflows`*** |
26+
| `AUTO_CREATE_NEW_BRANCH` | ***false*** | Auto create new brach in a repository if the branch dose not exists |
27+
| `COMMIT_EACH_FILE` | ***false*** | if you need to keep track of each file's commit history separate then set it to true |
2328

2429
### Personal Access Token Scope
2530
#### [Github Personal Token](https://github.com/settings/tokens/new?description=gh-workflow-sync) <small> Is required with the below scope </small>
@@ -31,30 +36,107 @@ _Example : [Project 1][project1] & [Project 2][project2] it can be pain to keep
3136
3237
***[Click Here To Generate A Token](https://github.com/settings/tokens/new?description=gh-workflow-sync)***
3338

34-
### `workflow_files`
35-
**Example**
39+
---
40+
41+
### `REPOSITORIES` Configuration Examples
42+
<details><summary><strong>Repository With Default Brach</strong></summary>
43+
44+
```yaml
45+
REPOSITORIES: |
46+
username/repo
47+
username/repo2
48+
```
49+
50+
</details>
51+
52+
<details><summary><strong>Repositry With Custom Branch</strong></summary>
53+
54+
```yaml
55+
REPOSITORIES: |
56+
username/repo@dev
57+
username/repo1@dev2
58+
```
59+
> You Can also have same repository multiple times if you provide different branch name
60+
</details>
61+
62+
---
63+
64+
### `WORKFLOW_FILES` Configuration Examples
65+
66+
<details><summary><strong>Files - Source & Destination File Without Custom Name</strong></summary>
67+
3668
```yaml
3769
WORKFLOW_FILES: |
38-
your-workflow-file1.yml
39-
your-workflow-file2.yml
70+
dependabot.yml
71+
.github/settings.yml
4072
```
73+
> **dependabot.yml** will save in root folder in the repository
74+
>
75+
> **.github/settings.yml** will save in `.github` in the repository
76+
77+
</details>
78+
79+
<details><summary><strong>Files - Source File In Root & Destination File In Custom Location</strong></summary>
80+
81+
```yaml
82+
WORKFLOW_FILES: |
83+
hello-bot.yml=.github/
84+
pr-bot.yml=.github/pull-request.yml
85+
```
86+
> **hello-bot.yml** will save in `.github` in the repository with the same name
87+
>
88+
> **pr-bot.yml** will save in `.github` in the repository with the name `pull-request.yml`
89+
</details>
90+
91+
<details><summary><strong>Folders - Source & Destination Folders Without Custom Name</strong></summary>
4192

42-
**Example | Custom File Location**
4393
```yaml
4494
WORKFLOW_FILES: |
45-
./your-folder/your-workflow-file1.yml
46-
./your-folder/your-workflow-file2.yml
95+
folder1
96+
.github/folder2
4797
```
98+
> **folder1** will save in root folder in the repository
99+
>
100+
> **.github/folder2** will save in `.github` in the repository
101+
102+
</details>
103+
104+
<details><summary><strong>Folders - Source & Destination Folders With Custom Name</strong></summary>
48105

49-
**Example | Custom File Name**
50-
Action will locate `your-workflow-file1.yml` from in your repository where this action is used & `your-custom-workflow-file.yml` will be the new file name which will be used to store in the repository you provided
51106
```yaml
52107
WORKFLOW_FILES: |
53-
./your-folder/your-workflow-file1.yml=your-custom-workflow-file.yml
108+
folder1=./save-to-folder
109+
.github/folder2=custom-folder/save-to-folder2
54110
```
111+
> **folder1** will save inside `REPOSITORY ROOT` in the name of `save-to-folder`
112+
>
113+
> **.github/folder2** will save inside `custom-folder` in the name of `save-to-folder2`
114+
115+
</details>
55116

56117
---
57118

119+
## How Files Sync Work ?
120+
Before copying the **WORKFLOW_FILES** from the source to destination. this action will provide some flexibility.
121+
this searchs for a file in various locations for example lets take `settings.yml` as the file that you want to sync for multiple repository
122+
123+
#### Below are the locations that this action search for the file/folder
124+
* `./{OWNER}/{REPO_NAME}/workflows/{filename}`
125+
* `./{OWNER}/workflows/{filename}`
126+
* `./{WORKFLOW_FILES_DIR}/{filename}`
127+
* `./.github/workflows/{filename}`
128+
* `./{OWNER}/{REPO_NAME}/{filename}`
129+
* `./{OWNER}/{filename}`
130+
* `./{filename}`
131+
132+
> if the `settings.yml` is found inside `workflows` folder then the destination is automaitcally forced to `.github/workflows` in the destination repo
133+
>
134+
> if the `settings.yml` is outside of `workflows` folder then the destination then its copied to the destination
135+
136+
### How this can be useful ?
137+
Lets assume that you want to maintain all the common github files in a single repository and suddenly a repository needs a single file to be changed in that case instead of editing the action yml file. you can just create a folder like `{REPO_OWNER}/{REPO_NAME}/{FILE}` to copy the overriden file to the destination
138+
139+
58140
## 🚀 Usage
59141

60142
### Step 1
@@ -65,7 +147,7 @@ if you have used our template repository then edit the file inside `.github/work
65147

66148
OR
67149

68-
Create a new file in `.github/workflows/` named ***workflow-sync.yml** and copy & paste the below file content
150+
Create a new file in `.github/workflows/` named **workflow-sync.yml** and copy & paste the below file content
69151

70152
#### `workflow-sync.yml` content
71153
```yaml
@@ -96,6 +178,36 @@ jobs:
96178
GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
97179
98180
```
181+
182+
## Troubleshooting
183+
184+
### Spacing
185+
Spacing around the equal sign is important. For example, this will not work:
186+
187+
```yaml
188+
WORKFLOW_FILES: |
189+
folder/file-sync.yml = folder/test.txt
190+
```
191+
192+
It passes to the shell file 3 distinct objects
193+
194+
* folder/file-sync.ymll
195+
* =
196+
* folder/test.txt
197+
198+
instead of 1 object
199+
200+
* folder/file-sync.yml = folder/test.txt
201+
202+
and there is nothing I can do in code to make up for that
203+
204+
### Slashes
205+
206+
You do not need (nor want) leading `/` for the file path on either side of the equal sign
207+
208+
The only time you need `/` trailing is for folder copies.
209+
While a file copy will technically still work with a leading `/`, a folder copy will not
210+
99211
---
100212

101213
## 📝 Changelog

0 commit comments

Comments
 (0)