|
| 1 | +# S3 Mirror |
| 2 | + |
| 3 | +Add GitHub data to your `README.md`, or any other file. |
| 4 | + |
| 5 | +A GitHub action that provides template strings that are replaced with their respective values when the action runs. |
| 6 | + |
| 7 | +By default, it takes `TEMPLATE.md` and outputs `README.md`. |
| 8 | + |
| 9 | +## Inputs |
| 10 | + |
| 11 | +| name | required | type | default | description | |
| 12 | +| ------------ | --- | ------ | --------------- | ----------- | |
| 13 | +| token | yes | string | | GitHub personal access token used to fetch data. Pass a secret by for instance using `${{ secrets.README_TEMPLATE_TOKEN }}`. [Go here](https://github.com/settings/tokens/new?scopes=read:user) to generate one with the `read:user` scope |
| 14 | +| template | yes | string | `"TEMPLATE.md"` | Template file path |
| 15 | +| readme | yes | string | `"README.md"` | Output file path |
| 16 | + |
| 17 | +## Example usage |
| 18 | + |
| 19 | +Check out [`example.yaml`](./example.yaml), that's how you can configure the binaries you would like to download. |
| 20 | + |
| 21 | +Workflow: |
| 22 | + |
| 23 | +```yaml |
| 24 | +name: S3 Mirror |
| 25 | +on: |
| 26 | + schedule: |
| 27 | + - cron: '0 1 * * *' # Every day at 1 am |
| 28 | + push: |
| 29 | + branches: [ main ] |
| 30 | +jobs: |
| 31 | + publish: |
| 32 | + runs-on: ubuntu-latest |
| 33 | + steps: |
| 34 | + - uses: actions/checkout@v2 |
| 35 | + with: |
| 36 | + fetch-depth: 0 |
| 37 | + - name: Generate README.md |
| 38 | + uses: buttahtoas/github-actions/s3-mirror@main |
| 39 | + with: |
| 40 | + token: ${{ secrets.README_TEMPLATE_TOKEN }} |
| 41 | + template: TEMPLATE.md |
| 42 | + output: README.md |
| 43 | +``` |
| 44 | +
|
| 45 | +`TEMPLATE.md`: |
| 46 | + |
| 47 | +````markdown |
| 48 | +My most starred repos: |
| 49 | +| ⭐️Stars | 📦Repo | 📚Description | |
| 50 | +| --------- | ----------- | -------------- | |
| 51 | +{{ loop 3_MOST_STARRED_REPOS }} |
| 52 | +| {{ REPO_STARS }} | [{{ REPO_FULL_NAME }}]({{ REPO_URL }}) | {{ REPO_DESCRIPTION }} | |
| 53 | +{{ end 3_MOST_STARRED_REPOS }} |
| 54 | +```` |
| 55 | + |
| 56 | +This generates the following output in my case: |
| 57 | + |
| 58 | +My most starred repos: |
| 59 | + |
| 60 | +| ⭐️Stars | 📦Repo | 📚Description | |
| 61 | +| --------- | ----------- | -------------- | |
| 62 | +| 10 | [probablykasper/chester-syntax](https://github.com/probablykasper/chester-syntax) | A pretty Atom syntax theme based on Lonely Planet colours | |
| 63 | +| 4 | [probablykasper/homebrew-tap](https://github.com/probablykasper/homebrew-tap) | My Homebrew casks and formulas | |
| 64 | +| 2 | [probablykasper/cryp](https://github.com/probablykasper/cryp) | Cryptocurrency portfolio tracker | |
| 65 | +| 1 | [probablykasper/notifier](https://github.com/probablykasper/notifier) | Flutter app for scheduling notifications | |
| 66 | +| 1 | [probablykasper/colorboy](https://github.com/probablykasper/colorboy) | Easy terminal coloring for Node.js, macOS/Linux | |
| 67 | + |
| 68 | +## Variables |
| 69 | + |
| 70 | +### Normal variables you can put into your template file |
| 71 | + |
| 72 | +| Variable | Example | |
| 73 | +| ------------------------ | ------- | |
| 74 | +| {{ USERNAME }} | probablykasper |
| 75 | +| {{ NAME }} | Kasper |
| 76 | + |
| 77 | +| {{ USER_ID }} | MDQ6VXNlcjExMzE1NDky |
| 78 | +| {{ BIO }} | Fullstack developer from Norway |
| 79 | +| {{ COMPANY }} | Microscopicsoft |
| 80 | +| {{ LOCATION }} | Norway |
| 81 | +| {{ TWITTER_USERNAME }} | probablykasper |
| 82 | +| {{ AVATAR_URL }} | https://avatars0.githubusercontent.com/u/11315492?u=c501da00e9b817ffc78faab6c630f236ac2738cf&v=4 |
| 83 | +| {{ WEBSITE_URL }} | https://kasper.space/ |
| 84 | +| {{ SIGNUP_TIMESTAMP }} | 2015-03-04T14:48:35Z |
| 85 | +| {{ SIGNUP_DATE }} | March 4th 2015 |
| 86 | +| {{ SIGNUP_DATE2 }} | 2015-03-04 |
| 87 | +| {{ SIGNUP_YEAR }} | 2015 |
| 88 | +| {{ SIGNUP_AGO }} | 5 years ago |
| 89 | +| {{ TOTAL_REPOS_SIZE_KB }} | 707453 |
| 90 | +| {{ TOTAL_REPOS_SIZE_MB }} | 707.5 |
| 91 | +| {{ TOTAL_REPOS_SIZE_GB }} | 0.71 |
| 92 | +| {{ TOTAL_REPOSITORIES }} | 46 |
| 93 | +| {{ CURRENT_REPO_FULL_NAME }} | probablykasper/readme-template-action |
| 94 | + |
| 95 | +### Variables you can put inside `repo` loops |
| 96 | + |
| 97 | +| Variable | Example | |
| 98 | +| ---------------------------- | ------- | |
| 99 | +| {{ REPO_NAME }} | cpc |
| 100 | +| {{ REPO_FULL_NAME }} | probablykasper/cpc |
| 101 | +| {{ REPO_DESCRIPTION }} | Text calculator with support for units and conversion |
| 102 | +| {{ REPO_URL }} | https://github.com/probablykasper/cpc |
| 103 | +| {{ REPO_HOMEPAGE_URL }} | https://rust-lang.org/ |
| 104 | +| {{ REPO_CREATED_TIMESTAMP }} | 2019-12-05T22:45:04Z |
| 105 | +| {{ REPO_PUSHED_TIMESTAMP }} | 2020-08-20T20:13:22Z |
| 106 | +| {{ REPO_FORK_COUNT }} | 2 |
| 107 | +| {{ REPO_ID }} | MDEwOlJlcG9zaXRvcnkyMjYyMDE5NTU= |
| 108 | +| {{ REPO_CREATED_DATE }} | December 5th 2019 |
| 109 | +| {{ REPO_CREATED_DATE2 }} | 2019-12-05 |
| 110 | +| {{ REPO_CREATED_YEAR }} | 2019 |
| 111 | +| {{ REPO_CREATED_AGO }} | 9 months ago |
| 112 | +| {{ REPO_PUSHED_DATE }} | August 20th 2020 |
| 113 | +| {{ REPO_PUSHED_DATE2 }} | 2020-08-20 |
| 114 | +| {{ REPO_PUSHED_YEAR }} | 2020 |
| 115 | +| {{ REPO_PUSHED_AGO }} | 3 days ago |
| 116 | +| {{ REPO_STARS }} | 5 |
| 117 | +| {{ REPO_LANGUAGE }} | Rust |
| 118 | +| {{ REPO_OWNER_USERNAME }} | probablykasper |
| 119 | +| {{ REPO_SIZE_KB }} | 1268285 |
| 120 | +| {{ REPO_SIZE_MB }} | 1268.3 |
| 121 | +| {{ REPO_SIZE_GB }} | 1.27 |
| 122 | + |
| 123 | +## Loops |
| 124 | + |
| 125 | +These are the built-in loops you can use. Data is only fetched for loops you use. |
| 126 | + |
| 127 | +<table> |
| 128 | + <thead> |
| 129 | + <tr> |
| 130 | + <td>Loop</td> |
| 131 | + <td>Type</td> |
| 132 | + <td>Description</td> |
| 133 | + </tr> |
| 134 | + </thead> |
| 135 | + <tbody> |
| 136 | + <tr> |
| 137 | + <td><code>3_MOST_STARRED_REPOS</code></td> |
| 138 | + <td>repos</td> |
| 139 | + <td> |
| 140 | + Fetches your 3 most starred repos. |
| 141 | + Uses the following parameters: |
| 142 | + <pre>first: 3,<br>privacy: PUBLIC,<br>ownerAffiliations:[OWNER],<br>orderBy: { field:STARGAZERS, direction: DESC }</pre> |
| 143 | + </td> |
| 144 | + </tr> |
| 145 | + <tr> |
| 146 | + <td><code>3_NEWEST_REPOS</code></td> |
| 147 | + <td>repos</td> |
| 148 | + <td> |
| 149 | + Fetches your 3 most starred repos. |
| 150 | + Uses the following parameters: |
| 151 | + <pre>first: 3,<br>privacy: PUBLIC,<br>ownerAffiliations:[OWNER],<br>orderBy: { field:CREATED_AT, direction: DESC }</pre> |
| 152 | + </td> |
| 153 | + </tr> |
| 154 | + <tr> |
| 155 | + <td><code>3_RECENTLY_PUSHED_REPOS</code></td> |
| 156 | + <td>repos</td> |
| 157 | + <td> |
| 158 | + Fetches your 3 most starred repos. |
| 159 | + Uses the following parameters: |
| 160 | + <pre>first: 3,<br>privacy: PUBLIC,<br>ownerAffiliations:[OWNER],<br>orderBy: { field:PUSHED_AT, direction: DESC }</pre> |
| 161 | + </td> |
| 162 | + </tr> |
| 163 | + </tbody> |
| 164 | +</table> |
| 165 | + |
| 166 | +## Advanced usage |
| 167 | + |
| 168 | +Check out [`EXAMPLE_TEMPLATE.md`](./EXAMPLE_TEMPLATE.md) and [`EXAMPLE_OUTPUT.md`](./EXAMPLE_OUTPUT.md) to see examples and their outputs. |
| 169 | + |
| 170 | +For advanced usage, add a code block like this to your template: |
| 171 | + |
| 172 | +````markdown |
| 173 | +```js |
| 174 | +// {{ TEMPLATE: }} |
| 175 | +module.exports = { |
| 176 | + // ... custom vairables/loops |
| 177 | +} |
| 178 | +// {{ :TEMPLATE }} |
| 179 | +```` |
| 180 | +
|
| 181 | +### List specific repos |
| 182 | +Get a list of specific repos |
| 183 | +
|
| 184 | +```js |
| 185 | + CUSTOM_PINNED_REPOS: { |
| 186 | + type: 'specificRepos', |
| 187 | + repos: [ 'vidl', 'golang/go', 'probablykasper/embler' ], |
| 188 | + }, |
| 189 | +``` |
| 190 | + |
| 191 | +### Repos with custom parameters |
| 192 | +Get repos using custom parameters: |
| 193 | + |
| 194 | +```js |
| 195 | + "2_MOST_STARRED_REPOS": { |
| 196 | + type: 'repos', |
| 197 | + params: ` |
| 198 | + first: 2, |
| 199 | + privacy: PUBLIC, |
| 200 | + ownerAffiliations:[OWNER], |
| 201 | + orderBy: { field:STARGAZERS, direction: DESC }, |
| 202 | + `, |
| 203 | + }, |
| 204 | +``` |
| 205 | + |
| 206 | +### Modify variables |
| 207 | +Add a `modifyVariables` function to overwrite/add variables: |
| 208 | + |
| 209 | +```js |
| 210 | + CUSTOM_PINNED_REPOS: { |
| 211 | + type: 'specificRepos', |
| 212 | + repos: [ 'vidl' ], |
| 213 | + modifyVariables: function(repo, moment, user) { |
| 214 | + repo.REPO_CREATED_MYDATE = moment(repo.REPO_CREATED_TIMESTAMP).format('YYYY MMMM Do') |
| 215 | + return repo |
| 216 | + }, |
| 217 | + }, |
| 218 | +``` |
| 219 | + |
| 220 | +### Custom queries |
| 221 | + |
| 222 | +```js |
| 223 | + LATEST_VIDL_RELEASE: { |
| 224 | + type: 'customQuery', |
| 225 | + loop: false, |
| 226 | + query: async (octokit, moment, user) => { |
| 227 | + // You can do anything you want with the GitHub API here. |
| 228 | + const result = await octokit.graphql(` |
| 229 | + query { |
| 230 | + repository(name: "vidl", owner: "${user.USERNAME}") { |
| 231 | + releases(last: 1) { |
| 232 | + edges { |
| 233 | + node { |
| 234 | + url |
| 235 | + publishedAt |
| 236 | + tagName |
| 237 | + } |
| 238 | + } |
| 239 | + } |
| 240 | + } |
| 241 | + } |
| 242 | + `) |
| 243 | + const release = result.repository.releases.edges[0].node |
| 244 | + const date = new Date(release.publishedAt) |
| 245 | + // We have `loop: false`, so we return an object. |
| 246 | + // If we had `loop: true`, we would return an array of objects. |
| 247 | + return { |
| 248 | + VIDL_RELEASE_TAG: release.tagName, |
| 249 | + VIDL_RELEASE_URL: release.url, |
| 250 | + VIDL_RELEASE_WHEN: moment(release.publishedAt).fromNow(), |
| 251 | + } |
| 252 | + } |
| 253 | + } |
| 254 | +``` |
| 255 | + |
| 256 | +## Dev instructions |
| 257 | + |
| 258 | +First, to get started: |
| 259 | + |
| 260 | +1. Install [Node.js](https://nodejs.org/) |
| 261 | +2. Run `npm install` |
| 262 | +3. [Go here](https://github.com/settings/tokens/new?scopes=read:user) to generate a GitHub personal access token with the `read:user` scope. |
| 263 | +4. Create a `.env` file like this, with your token: |
| 264 | + |
| 265 | +```env |
| 266 | +INPUT_TOKEN=mytoken |
| 267 | +INPUT_TEMPLATE=EXAMPLE_TEMPLATE.md |
| 268 | +INPUT_OUTPUT=EXAMPLE_OUTPUT.md |
| 269 | +``` |
| 270 | + |
| 271 | +Now you can test the action by running the following command: |
| 272 | + |
| 273 | +```sh |
| 274 | +npm run test |
| 275 | +``` |
| 276 | + |
| 277 | +Build: |
| 278 | +```sh |
| 279 | +npm run build |
| 280 | +``` |
0 commit comments