Skip to content

Commit 6e97d64

Browse files
bubkoobubkoo
committed
docs: update usage
1 parent 11286d9 commit 6e97d64

File tree

2 files changed

+45
-51
lines changed

2 files changed

+45
-51
lines changed

‎README.md‎

Lines changed: 43 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<h1 align="center">🔑 Use App Token</h1>
22

3-
<p align="center">Run GitHub Actions as a GitHub App by using the app's authentication token<strong></strong></p>
3+
<p align="center"><strong>Run GitHub Actions as a GitHub App by using the app's authentication token</strong></p>
44

55
<p align="center">
66
<a href="/wow-actions/use-app-token/blob/master/LICENSE"><img alt="MIT License" src="https://img.shields.io/github/license/wow-actions/use-app-token?style=flat-square"></a>
@@ -11,42 +11,40 @@
1111
<a href="https://lgtm.com/projects/g/wow-actions/use-app-token/context:javascript" rel="nofollow"><img alt="Language grade: JavaScript" src="https://img.shields.io/lgtm/grade/javascript/g/wow-actions/use-app-token.svg?logo=lgtm&style=flat-square" ></a>
1212
</p>
1313

14-
This GitHub Action can be used to impersonate a GitHub App when `secrets.GITHUB_TOKEN`'s limitations are too restrictive and a personal access token is not suitable.
15-
16-
[`secrets.GITHUB_TOKEN`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) has limitations such as [not being able to triggering a new workflow from another workflow](https://github.community/t5/GitHub-Actions/Triggering-a-new-workflow-from-another-workflow/td-p/31676). A workaround is to use a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) from a [personal user/bot account](https://help.github.com/en/github/getting-started-with-github/types-of-github-accounts#personal-user-accounts). However, for organizations, GitHub Apps are [a more appropriate automation solution](https://developer.github.com/apps/differences-between-apps/#machine-vs-bot-accounts).
14+
This GitHub Action can be used to **impersonate** a GitHub App when `secrets.GITHUB_TOKEN`'s limitations are too restrictive and a personal access token is not suitable. [`secrets.GITHUB_TOKEN`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) has limitations such as [not being able to triggering a new workflow from another workflow](https://github.community/t5/GitHub-Actions/Triggering-a-new-workflow-from-another-workflow/td-p/31676). A workaround is to use a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) from a [personal user/bot account](https://help.github.com/en/github/getting-started-with-github/types-of-github-accounts#personal-user-accounts). However, for organizations, GitHub Apps are [a more appropriate automation solution](https://developer.github.com/apps/differences-between-apps/#machine-vs-bot-accounts).
1715

1816
We can also use an app token to [custom an action's name and avatar](https://github.community/t/change-bots-name-avatar/18349).
1917

2018
![screenshot](https://github.com/wow-actions/use-app-token/blob/master/screenshots/screenshot.jpg?raw=true)
2119

22-
## 🚀 Usage
20+
## Usage
2321

2422
Before staring, we should get our owned app's _"APP ID"_ and _"Private Key"_ in the app's setting page. For example, find the two values in my app's setting page [https://github.com/settings/apps/wow-actions-bot](https://github.com/settings/apps/wow-actions-bot).
2523

26-
Get your owned app's _"APP ID"_:
24+
Get your owned app's _"APP ID"_
2725

2826
![get-app-id](https://github.com/wow-actions/use-app-token/blob/master/screenshots/get-app-id.jpg?raw=true)
2927

30-
Get or create a _"Private Key"_:
28+
Get or create a _"Private Key"_
3129

3230
![get-private-key](https://github.com/wow-actions/use-app-token/blob/master/screenshots/get-private-key.jpg?raw=true)
3331

3432
**Do not have a Github App? Get a quick start with [probot](https://probot.github.io/).**
3533

36-
Then add _"APP ID"_ and _"Private Key"_ to the target [repo's secrets](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets). For example, we can add two secrets named `APP_ID` and `PRIVATE_KEY` with corresponding value.
34+
Then add _"APP ID"_ and _"Private Key"_ to the target [repo's secrets](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets). For example, we can add two secrets named `APP_ID` and `PRIVATE_KEY` with corresponding values.
3735

3836
![secrets](https://github.com/wow-actions/use-app-token/blob/master/screenshots/secrets.jpg?raw=true)
3937

40-
Now we can config the action by three ways:
38+
Now we can config our workflows.
4139

42-
**Method 1**: Use action's output in the next steps.
40+
### Method 1: Use action's output in the next steps
4341

4442
```yml
4543
jobs:
4644
run:
4745
runs-on: ubuntu-latest
4846
steps:
49-
- uses: wow-actions/use-app-token@v1
47+
- uses: wow-actions/use-app-token@v2
5048
id: generate_token
5149
with:
5250
app_id: ${{ secrets.APP_ID }}
@@ -55,79 +53,75 @@ jobs:
5553
# Use token in next steps
5654
- uses: 'any other action'
5755
with:
58-
# Use token in outpus of the 'generate_token' step
59-
GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
56+
# Use app token in outpus of the 'generate_token' step
57+
GITHUB_TOKEN: ${{ steps.generate_token.outputs.BOT_TOKEN }}
58+
# Use app name in outpus of the 'generate_token' step
59+
GIT_COMMITTER_NAME: ${{ steps.generate_token.outputs.BOT_NAME }}
60+
GIT_COMMITTER_EMAIL: ${{ steps.generate_token.outputs.BOT_NAME }}@users.noreply.github.com
6061
```
6162
62-
**Method 2**: Set an environment variable and used in the next step.
63+
### Method 2: Use environment variables in the next steps
6364
6465
```yml
6566
jobs:
6667
run:
6768
runs-on: ubuntu-latest
6869
steps:
69-
- uses: wow-actions/use-app-token@v1
70-
id: generate_token
70+
- uses: wow-actions/use-app-token@v2
7171
with:
7272
app_id: ${{ secrets.APP_ID }}
7373
private_key: ${{ secrets.PRIVATE_KEY }}
74-
# save app's token to the environment variable named "bot_token"
75-
env_name: bot_token
7674

7775
# Use token in next steps
7876
- uses: 'any other action'
7977
with:
80-
# Use token in the environment variable named "bot_token"
81-
GITHUB_TOKEN: ${{ env.bot_token }}
78+
# Use app token in the environment variable named "BOT_TOKEN"
79+
GITHUB_TOKEN: ${{ env.BOT_TOKEN }}
80+
# Use app name in the environment variable named "BOT_NAME"
81+
GIT_COMMITTER_NAME: ${{ env.BOT_NAME }}
82+
GIT_COMMITTER_EMAIL: ${{ env.BOT_NAME }}@users.noreply.github.com
83+
84+
8285
```
8386

84-
**Method 3**: Add or update an secret in the target repo schedulely.
87+
### Method 3: Use secrets in the next steps
8588

8689
```yml
87-
name: Use App Token
88-
on:
89-
schedule:
90-
# add or update secret every hour
91-
- cron: '0 */1 * * *'
9290
jobs:
9391
run:
9492
runs-on: ubuntu-latest
9593
steps:
96-
- uses: wow-actions/use-app-token@v1
94+
- uses: wow-actions/use-app-token@v2
9795
with:
9896
app_id: ${{ secrets.APP_ID }}
9997
private_key: ${{ secrets.PRIVATE_KEY }}
100-
# The secret name
101-
secret_name: BOT_TOKEN
102-
```
103-
104-
Then we can use the secret named `'BOT_TOKEN'` in the next steps.
105-
106-
```yml
107-
jobs:
108-
run:
109-
runs-on: ubuntu-latest
110-
steps:
98+
# Specify true to save app token and app slug into the secrets of current repository
99+
secret: true
100+
# Specify true to clean saved secrets when workflow run completed
101+
clean: true
111102
- uses: 'any other action'
112103
with:
113104
GITHUB_TOKEN: ${{ secrets.BOT_TOKEN }}
105+
GIT_COMMITTER_NAME: ${{ secrets.BOT_NAME }}
106+
GIT_COMMITTER_EMAIL: ${{ secrets.BOT_NAME }}@users.noreply.github.com
114107
```
115108
116-
### 🎛️ Inputs
109+
### Inputs
117110
118111
Various inputs are defined to let you configure the action:
119112
120113
> Note: [Workflow command and parameter names are not case-sensitive](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#about-workflow-commands).
121114
122-
| Name | Description | Default |
123-
| --- | --- | :-: |
124-
| `app_id` | The ID of the GitHub App. [Create an secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `'APP_ID'` to store your app ID, then used by `${{ secrets.APP_ID }}` | N/A |
125-
| `private_key` | The private key of the GitHub App (can be Base64 encoded). [Create an secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `'PRIVATE_KEY'` to store your app private key, then used by `${{ secrets.APP_ID }}` | N/A |
126-
| `fallback` | The fallback token when app token generate failed | |
127-
| `env_name` | The name of generated token in exported environment variable. Specify a varable name will set an environment variable with specfiied name and valued with generated token, and can be use in next step with `${{ env.env_name }}` | |
128-
| `secret_name` | The name of the secret created on current repository. Specify a secret name will add an secret on current repository with specfiied name and valued with generated token and can be use in next step with `${{ secrets.xxx }}` | |
129-
| `clean_secret` | Shoule clean the secret or not when the job completed. Only used when `secret_name` specfiied | `false` |
130-
131-
## ⚖️ License
115+
| Name | Description | Default |
116+
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------:|
117+
| `app_id` | The ID of the GitHub App. [Create an secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `'APP_ID'` to store your app ID, then used by `${{ secrets.APP_ID }}` | N/A |
118+
| `private_key` | The private key of the GitHub App (can be Base64 encoded). [Create an secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `'PRIVATE_KEY'` to store your app private key, then used by `${{ secrets.APP_ID }}` | N/A |
119+
| `fallback` | The fallback token when app token generate failed | N/A |
120+
| `app_slug_name` | The app slug name exported to `env` or saved to `secrets` | `"BOT_NAME"` |
121+
| `app_token_name` | The app token name exported to `env` or saved to `secrets` | `"BOT_TOKEN"` |
122+
| `secret` | Specify `true` to save app token and app slug into the secrets of current repository | `false` |
123+
| `clean` | Specify `true` to clean saved secrets when workflow run completed. Only used when `secret` specfiied to `true` | `true` |
124+
125+
## License
132126

133127
The scripts and documentation in this project are released under the [MIT License](LICENSE)

‎action.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@ inputs:
1212
description: The fallback token when bot token generate failed.
1313
required: false
1414
app_slug_name:
15-
description: The app login name exported to `env` or saved to `secrets`.
15+
description: The app slug name exported to `env` or saved to `secrets`.
1616
required: false
1717
default: BOT_NAME
1818
app_token_name:
1919
description: The app token name exported to `env` or saved to `secrets`.
2020
required: false
2121
default: BOT_TOKEN
2222
secret:
23-
description: Specify true to save app token and app login name into the secrets of current repository.
23+
description: Specify true to save app token and app slug into the secrets of current repository.
2424
required: false
2525
default: false
2626
clean:

0 commit comments

Comments
 (0)