Skip to content

Commit 279e84f

Browse files
peter-evanspeter-evans
committed
Update examples
1 parent 302daa7 commit 279e84f

File tree

1 file changed

+132
-8
lines changed

1 file changed

+132
-8
lines changed

‎docs/examples.md

Lines changed: 132 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,19 @@
11
# Examples
22

3-
This document details command patterns and examples.
4-
53
- [Use case: Execute command using a specific repository branch](#execute-command-using-a-specific-repository-branch)
4+
- [pytest](#pytest)
65
- [Use case: Execute command to modify a pull request branch](#execute-command-to-modify-a-pull-request-branch)
76

87
## Use case: Execute command using a specific repository branch
98

10-
This is pattern for a slash command where the first argument is the branch to checkout. If no argument is given it defaults to `master`. For example, the following command will cause the command workflow to checkout the `develop` branch of the repository where the command was dispatched from. After the branch has been checked out in the command workflow, scripts or actions may be executed against it.
9+
This is pattern for a slash command where a named argument specifies the branch to checkout. If the named argument is missing it defaults to `master`. For example, the following command will cause the command workflow to checkout the `develop` branch of the repository where the command was dispatched from. After the branch has been checked out in the command workflow, scripts, tools or actions may be executed against it.
1110

1211
```
13-
/do-something develop
12+
/do-something branch=develop
1413
```
1514

15+
In the dispatch configuration for this command pattern, `named-args` should be set to `true`.
16+
1617
In the following command workflow, `REPO_ACCESS_TOKEN` is a `repo` scoped [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
1718

1819
```yml
@@ -28,7 +29,7 @@ jobs:
2829
- name: Get the target branch name
2930
id: vars
3031
run: |
31-
branch=${{ github.event.client_payload.slash_command.arg1 }}
32+
branch=${{ github.event.client_payload.slash_command.branch }}
3233
if [[ -z "$branch" ]]; then branch="master"; fi
3334
echo ::set-output name=branch::$branch
3435
@@ -39,9 +40,73 @@ jobs:
3940
repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
4041
ref: ${{ steps.vars.outputs.branch }}
4142

42-
# Execute scripts or actions
43+
# Execute scripts, tools or actions
4344
- name: Do something
44-
run: echo "Do something"
45+
run: |
46+
# Execute a script, tool or action here
47+
#
48+
echo "Do something"
49+
50+
# Add reaction to the comment
51+
- name: Add reaction
52+
uses: peter-evans/create-or-update-comment@v1
53+
with:
54+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
55+
repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
56+
comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
57+
reaction-type: hooray
58+
```
59+
60+
### pytest
61+
62+
This is a real example that uses this pattern to execute the Python test tool `pytest` against a specific branch.
63+
64+
```
65+
/pytest branch=develop -v -s
66+
```
67+
68+
In the following command workflow, note how the remaining `unnamed_args` are passed to the `pytest` tool.
69+
70+
```yml
71+
name: pytest
72+
on:
73+
repository_dispatch:
74+
types: [pytest-command]
75+
jobs:
76+
pytest:
77+
runs-on: ubuntu-latest
78+
steps:
79+
# Get the branch name
80+
- name: Get the target branch name
81+
id: vars
82+
run: |
83+
branch=${{ github.event.client_payload.slash_command.branch }}
84+
if [[ -z "$branch" ]]; then branch="master"; fi
85+
echo ::set-output name=branch::$branch
86+
87+
# Checkout the branch to test
88+
- uses: actions/checkout@v2
89+
with:
90+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
91+
repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
92+
ref: ${{ steps.vars.outputs.branch }}
93+
94+
# Setup Python environment
95+
- uses: actions/setup-python@v1
96+
97+
# Install pytest
98+
- name: Install pytest
99+
run: |
100+
pip install -U pytest
101+
pytest --version
102+
103+
# Install requirements
104+
- name: Install requirements
105+
run: pip install -r requirements.txt
106+
107+
# Execute pytest
108+
- name: Execute pytest
109+
run: pytest ${{ github.event.client_payload.slash_command.unnamed_args }}
45110
46111
# Add reaction to the comment
47112
- name: Add reaction
@@ -55,12 +120,14 @@ jobs:
55120

56121
## Use case: Execute command to modify a pull request branch
57122

58-
This is pattern for a slash command used in pull request comments. It checks out the pull request branch and allows further script and action steps to modify it.
123+
This is pattern for a slash command used in pull request comments. It checks out the pull request branch and allows further scripts, tools and action steps to modify it.
59124

60125
```
61126
/fix-pr
62127
```
63128

129+
In the dispatch configuration for this command pattern, `issue-type` should be set to `pull-request`. This will prevent it from being dispatched from regular issue comments where it will fail.
130+
64131
In the following command workflow, `REPO_ACCESS_TOKEN` is a `repo` scoped [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
65132

66133
```yml
@@ -97,3 +164,60 @@ jobs:
97164
comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
98165
reaction-type: hooray
99166
```
167+
168+
### black
169+
170+
This is a real example that uses this pattern to format Python code using [black](https://github.com/psf/black).
171+
172+
```
173+
/black
174+
```
175+
176+
In the following command workflow, note how a step `if` condition checks to see if anything should be committed.
177+
178+
```yml
179+
name: black-command
180+
on:
181+
repository_dispatch:
182+
types: [black-command]
183+
jobs:
184+
black:
185+
runs-on: ubuntu-latest
186+
steps:
187+
# Checkout the pull request branch
188+
- uses: actions/checkout@v2
189+
with:
190+
token: ${{ secrets.ACTIONS_BOT_TOKEN }}
191+
repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }}
192+
ref: ${{ github.event.client_payload.pull_request.head.ref }}
193+
194+
# Setup Python environment
195+
- uses: actions/setup-python@v1
196+
197+
# Install black
198+
- name: Install black
199+
run: pip install black
200+
201+
# Execute black in check mode
202+
- name: Black
203+
id: black
204+
run: echo ::set-output name=format::$(black --check --quiet . || echo "true")
205+
206+
# Execute black and commit the change to the PR branch
207+
- name: Commit to the PR branch
208+
if: steps.black.outputs.format == 'true'
209+
run: |
210+
black .
211+
git config --global user.name 'actions-bot'
212+
git config --global user.email '[email protected]'
213+
git commit -am "[black-command] fixes"
214+
git push
215+
216+
- name: Add reaction
217+
uses: peter-evans/create-or-update-comment@v1
218+
with:
219+
token: ${{ secrets.ACTIONS_BOT_TOKEN }}
220+
repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
221+
comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
222+
reaction-type: hooray
223+
```

0 commit comments

Comments
 (0)