Skip to content

Commit 91ee328

Browse files
saadmk11saadmk11
authored
Merge pull request #27 from saadmk11/docs-improvement
Improve Documentation
2 parents b49419d + 180726c commit 91ee328

2 files changed

Lines changed: 77 additions & 43 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
and create a **pull request** with the updates (if enabled).
1111
It is an automated dependency updater similar to GitHub's **Dependabot** but for GitHub Actions.
1212

13-
### How Does It Work:
13+
### How Does It Work?
1414

1515
* GitHub Actions Version Updater first goes through all the **workflows**
1616
in a repository and **checks for updates** for each of the action used in those workflows.
@@ -22,21 +22,78 @@ It is an automated dependency updater similar to GitHub's **Dependabot** but for
2222

2323
* Finally, a pull request is created with the newly created branch. (If enabled)
2424

25-
### Supported Version Fetch Sources:
25+
### Supported Version Fetch Sources
2626

27-
- **`release-tag`** (default): Uses **specific version tag** from **the latest release** to update a GitHub Action. (e.g. `actions/checkout@v1.2.3`)
28-
- **`release-commit-sha`**: Uses **the latest release** tag **commit SHA** to update a GitHub Action. (e.g. `actions/checkout@c18e2a1b1a95d0c5c63af210857e8718a479f56f`)
29-
- **`default-branch-sha`**: Uses **default branch** (e.g: `main`, `master`) **latest commit SHA** to update a GitHub Action. (e.g. `actions/checkout@c18e2a1b1a95d0c5c63af210857e8718a479f56f`)
27+
- **`release-tag` (default):** Uses **specific release tag** from **the latest release** to update a GitHub Action. (e.g. `actions/checkout@v1.2.3`)
28+
29+
- **`release-commit-sha`:** Uses the **latest release tag commit SHA** to update a GitHub Action. (e.g. `actions/checkout@c18e2a1b1a95d0c5c63af210857e8718a479f56f`)
30+
31+
- **`default-branch-sha`:** Uses **default branch** (e.g: `main`, `master`) **latest commit SHA** to update a GitHub Action. (e.g. `actions/checkout@c18e2a1b1a95d0c5c63af210857e8718a479f56f`)
3032

3133
You can use `update_version_with` input option to select one of them. (e.g. `update_version_with: 'default-branch-sha'`)
3234

33-
### Usage:
35+
### Release Types
36+
37+
- **`all` (default):** Actions with **any** new release will be updated.
38+
- **`major`:** Actions with only new **major** release will be updated.
39+
- **`minor`:** Actions with only new **minor** release will be updated.
40+
- **`patch`:** Actions with only new **patch** release will be updated.
41+
42+
You can use `release_types` input option to select one/all of them. (e.g. `"major, minor"`)
43+
44+
### Usage
3445

3546
We recommend running this action on a [`schedule`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule)
3647
event or a [`workflow_dispatch`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) event.
3748

3849
To integrate `GitHub Actions Version Updater` on your repository, create a `YAML` file
39-
inside `.github/workflows/` directory (`.github/workflows/updater.yaml`) add the following into the file:
50+
inside `.github/workflows/` directory (e.g: `.github/workflows/updater.yaml`) add the following lines into the file:
51+
52+
```yaml
53+
name: GitHub Actions Version Updater
54+
55+
# Controls when the action will run.
56+
on:
57+
schedule:
58+
# Automatically run on every Sunday
59+
- cron: '0 0 * * 0'
60+
61+
jobs:
62+
build:
63+
runs-on: ubuntu-latest
64+
65+
steps:
66+
- uses: actions/checkout@v2
67+
with:
68+
# [Required] Access token with `workflow` scope.
69+
token: ${{ secrets.WORKFLOW_SECRET }}
70+
71+
- name: Run GitHub Actions Version Updater
72+
uses: saadmk11/github-actions-version-updater@v0.5.6
73+
with:
74+
# [Required] Access token with `workflow` scope.
75+
token: ${{ secrets.WORKFLOW_SECRET }}
76+
```
77+
78+
### Workflow input options
79+
80+
These are the inputs that can be provided on the workflow.
81+
82+
| Name | Required | Description | Default | Example |
83+
|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------|-----------------------------------------|
84+
| `token` | Yes | GitHub Access Token with `workflow` scope (The Token needs to be added to the actions secrets) | `null` | `${{ secrets.WORKFLOW_SECRET }}` |
85+
| `committer_username` | No | Name of the user who will commit the changes to GitHub | "github-actions[bot]" | "Test User" |
86+
| `committer_email` | No | Email Address of the user who will commit the changes to GitHub | "github-actions[bot]@users.noreply.github.com" | "test@test.com" |
87+
| `commit_message` | No | Commit message for the commits created by the action | "Update GitHub Action Versions" | "Custom Commit Message" |
88+
| `pull_request_title` | No | Title of the pull requests generated by the action | "Update GitHub Action Versions" | "Custom PR Title" |
89+
| `ignore` | No | A comma separated string of GitHub Actions to ignore updates for | `null` | "actions/checkout@v2, actions/cache@v2" |
90+
| `skip_pull_request` | No | If **"true"**, the action will only check for updates and if any update is found the job will fail and update the build summary with the diff (**Options:** "true", "false") | "false" | "true" |
91+
| `update_version_with` | No | Use The Latest Release Tag/Commit SHA or Default Branch Commit SHA to update the actions (**options:** "release-tag", "release-commit-sha", "default-branch-sha"') | "release-tag" | "release-commit-sha" |
92+
| `release_types` | No | A comma separated string of release types to use when updating the actions. By default, all release types are used to update the actions. Only Applicable for **"release-tag", "release-commit-sha"** (**Options:** "major", "minor", "patch" **[one or many seperated by comma]**) | "all" | "minor, patch" |
93+
| `pull_request_user_reviewers` | No | A comma separated string (usernames) which denotes the users that should be added as reviewers to the pull request | `null` | "octocat, hubot, other_user" |
94+
| `pull_request_team_reviewers` | No | A comma separated string (team slugs) which denotes the teams that should be added as reviewers to the pull request | `null` | "justice-league, other_team" |
95+
96+
#### Workflow with all options
4097

4198
```yaml
4299
name: GitHub Actions Version Updater
@@ -56,50 +113,27 @@ jobs:
56113
steps:
57114
- uses: actions/checkout@v2
58115
with:
59-
# Access token with `workflow` scope is required
116+
# [Required] Access token with `workflow` scope.
60117
token: ${{ secrets.WORKFLOW_SECRET }}
61118

62119
- name: Run GitHub Actions Version Updater
63120
uses: saadmk11/github-actions-version-updater@v0.5.6
64121
with:
65122
# [Required] Access token with `workflow` scope.
66123
token: ${{ secrets.WORKFLOW_SECRET }}
67-
# [Optional] This will be used to configure git
68-
# defaults to `github-actions[bot]` if not provided
69-
committer_username: 'test'
124+
committer_username: 'Test'
70125
committer_email: 'test@test.com'
71-
# [Optional] Allows customizing the commit message
72-
# defaults to 'Update GitHub Action Versions'
73126
commit_message: 'Commit Message'
74-
# [Optional] Allows customizing the pull request title
75-
# defaults to 'Update GitHub Action Versions'
76127
pull_request_title: 'Pull Request Title'
77-
# [Optional] A comma separated string of GitHub Actions to ignore updates for.
78-
# e.g: 'actions/checkout@v2, actions/cache@v2'
79128
ignore: 'actions/checkout@v2, actions/cache@v2'
80-
# [Optional] If set to 'true', the action will only check for updates and
81-
# exit with a non-zero exit code if an update is found and update the build summary with the diff
82-
# otherwise it will create a pull request with the changes
83-
# options: 'false' (default), 'true'
84129
skip_pull_request: 'false'
85-
# [Optional] Use The Latest Release Tag/Commit SHA or Default Branch Commit SHA to update the actions
86-
# options: "release-tag" (default), "release-commit-sha", "default-branch-sha"'
87130
update_version_with: 'release-tag'
88-
# [Optional] A comma separated string of release types (major, minor, patch) to use when updating the actions
89-
# If not specified, all releases will be used
90-
# By default, all (major, minor, patch) release types are used to update the actions
91-
# Only applicable for `release-tag` and `release-commit-sha` update_version_with options
92-
# options: "all" (default), "major", "minor", "patch"
93-
release_types: 'all'
94-
# [Optional] A comma separated string (usernames) which denotes the users
95-
# that should be added as reviewers to the pull request
131+
release_types: "minor, patch"
96132
pull_request_user_reviewers: "octocat, hubot, other_user"
97-
# [Optional] A comma separated string (team slugs) which denotes the teams
98-
# that should be added as reviewers to the pull request
99133
pull_request_team_reviewers: "justice-league, other_team"
100134
```
101135
102-
### Important Note:
136+
### Important Note
103137
104138
GitHub does not allow updating workflow files inside a workflow run.
105139
The token generated by GitHub in every workflow (`${{secrets.GITHUB_TOKEN}}`) does not have
@@ -108,7 +142,7 @@ with **repo** and **workflow** scope and pass it to the action.
108142

109143
To know more about how to pass a secret to GitHub actions you can [Read GitHub Docs](https://docs.github.com/en/actions/reference/encrypted-secrets)
110144

111-
### GitHub Actions Version Updater in Action:
145+
### GitHub Actions Version Updater in Action
112146

113147
![GitHub Actions Version Updater Demo](https://github.com/__user-images/24854406/113888349-15dbdc00-97e4-11eb-91a6-622828455d1f.gif)
114148

‎action.yaml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,38 @@ branding:
66
color: 'green'
77
inputs:
88
committer_username:
9-
description: 'Username of that user who will commit'
9+
description: 'Name of the user who will commit the changes to GitHub'
1010
required: false
1111
default: 'github-actions[bot]'
1212
committer_email:
13-
description: 'Email Address of that user who will commit'
13+
description: 'Email Address of the user who will commit the changes to GitHub'
1414
required: false
1515
default: 'github-actions[bot]@users.noreply.github.com'
1616
commit_message:
17-
description: 'Commit message for the commits by the action'
17+
description: 'Commit message for the commits created by the action'
1818
required: false
1919
default: 'Update GitHub Action Versions'
2020
pull_request_title:
21-
description: 'Title for the pull requests generated by the action'
21+
description: 'Title of the pull requests generated by the action'
2222
required: false
2323
default: 'Update GitHub Action Versions'
2424
ignore:
25-
description: 'A JSON array or comma separated string which denotes the actions that should not be updated'
25+
description: 'A comma separated string of GitHub Actions to ignore updates for'
2626
required: false
2727
default: ''
2828
token:
29-
description: 'Personal Access token with workflow permission'
29+
description: 'GitHub Personal Access Token with `workflow` scope'
3030
required: true
3131
skip_pull_request:
3232
description: 'Skip Pull Request creation'
3333
required: false
3434
default: 'false'
3535
update_version_with:
36-
description: 'Use Latest Release Tag/Commit SHA or Default Branch Commit SHA to update. options: "release-tag" (default), "release-commit-sha", "default-branch-sha"'
36+
description: 'Use The Latest Release Tag/Commit SHA or Default Branch Commit SHA to update the actions. options: "release-tag" (default), "release-commit-sha", "default-branch-sha"'
3737
required: false
3838
default: 'release-tag'
3939
release_types:
40-
description: 'A comma separated string of release types (major, minor, patch) to use when updating the actions. If not specified, all releases will be used. options: "all" (default), "major", "minor", "patch"'
40+
description: 'A comma separated string of release types (major, minor, patch) to use when updating the actions. By default, all release types are used to update the actions. Only Applicable for "release-tag", "release-commit-sha"'
4141
required: false
4242
default: 'all'
4343
pull_request_user_reviewers:

0 commit comments

Comments
 (0)