Skip to content

Commit 546aa52

Browse files
bitwizeshiftbitwizeshift
committed
📄 Add generated documentation
This will eventually be moved to an automated workflow process; but for now, this chekcs in the content as-is so that it's easier to view.
1 parent 409fca5 commit 546aa52

18 files changed

+950
-2
lines changed

‎README.md‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,39 @@
11
# `actions-github`
22

3-
This repository contains a series of composite actions that build upon
4-
[`actions/github-script`][github-script], and provides basic interactions.
3+
This repository provides easy-to-use [composite actions] for managing a Github
4+
repository in [Github workflows]. All actions wrap the [octokit api] via
5+
[`actions/github-script`][github-script].
56

7+
## Available Actions
8+
9+
Below are the list of available actions, with links to documentation:
10+
11+
* [`issues/add-assignees`](docs/issues-add-assignees.md)
12+
* [`issues/add-labels`](docs/issues-add-labels.md)
13+
* [`issues/close`](docs/issues-close.md)
14+
* [`issues/create`](docs/issues-create.md)
15+
* [`issues/create-comment`](docs/issues-create-comment.md)
16+
* [`issues/create-or-comment`](docs/issues-create-or-comment.md)
17+
* [`issues/delete-comment`](docs/issues-delete-comment.md)
18+
* [`issues/get`](docs/issues-get.md)
19+
* [`issues/lock`](docs/issues-lock.md)
20+
* [`issues/remove-assignee`](docs/issues-remove-assignee.md)
21+
* [`issues/remove-label`](docs/issues-remove-label.md)
22+
* [`issues/set-labels`](docs/issues-set-labels.md)
23+
* [`issues/unlock`](docs/issues-unlock.md)
24+
* [`issues/update-comment`](docs/issues-update-comment.md)
25+
* [`releases/create`](docs/releases-create.md)
26+
* [`releases/delete`](docs/releases-delete.md)
27+
* [`releases/upload-asset`](docs/releases-upload-asset.md)
28+
29+
## License
30+
31+
Except where otherwise specified, this project is dual-licensed under both the
32+
[Apache-2] and [MIT] licenses.
33+
34+
[Apache-2]: https://opensource.org/license/apache-2-0/
35+
[MIT]: http://opensource.org/licenses/MIT/
36+
[composite actions]: https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
37+
[octokit api]: https://octokit.github.io/rest.js/v20
38+
[Github workflows]: https://docs.github.com/en/actions/using-workflows
639
[github-script]: https://github.com/actions/github-script

‎docs/issues-add-assignees.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Add assignees to issue
2+
3+
<!-- These docs are generated by a tool -->
4+
5+
A composite action for adding assignees to github issues.
6+
This requires `issues: write` permissions in order to work correctly.
7+
8+
## Inputs
9+
10+
| Name | Description | Default |
11+
|------|-------------|---------|
12+
| `assignees` (*) | A list of labels to add, separated by newlines. | _N/A_ |
13+
| `issue-number` | The issue number to comment on | `"0"` |
14+
| `owner` | The repository owner | `""` |
15+
| `repo` | The repository | `""` |
16+
| `retries` | The number of times to try retrying | `"0"` |
17+
| `retry-exempt-status-codes` | The retry exempt status codes | `"400,401,403,404,422"` |
18+
19+
**Note:** _(*) marks required inputs_
20+
21+
## Outputs
22+
23+
`issues/add-assignees` does not have any outputs at this time
24+
25+
## Example
26+
27+
Here is a very basic example of how to use the `issues/add-assignees` composite action
28+
in a project (placeholders are used in place of real inputs):
29+
30+
```yaml
31+
run:
32+
example-job:
33+
# ...
34+
steps:
35+
# ...
36+
- name: Add assignees to issue
37+
uses: bitwizeshift/actions-github/issues/add-assignees@v1
38+
with:
39+
# Required inputs
40+
assignees: ASSIGNEES
41+
42+
# Optional inputs
43+
issue-number: ISSUE_NUMBER
44+
owner: OWNER
45+
repo: REPO
46+
retries: RETRIES
47+
retry-exempt-status-codes: RETRY_EXEMPT_STATUS_CODES
48+
```

‎docs/issues-add-labels.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Add labels to issue
2+
3+
<!-- These docs are generated by a tool -->
4+
5+
A composite action for adding labels to github issues.
6+
This requires `issues: write` permissions in order to work correctly.
7+
8+
## Inputs
9+
10+
| Name | Description | Default |
11+
|------|-------------|---------|
12+
| `labels` (*) | A list of labels to add, separated by newlines. | _N/A_ |
13+
| `issue-number` | The issue number to comment on | `"0"` |
14+
| `owner` | The repository owner | `""` |
15+
| `repo` | The repository | `""` |
16+
| `retries` | The number of times to try retrying | `"0"` |
17+
| `retry-exempt-status-codes` | The retry exempt status codes | `"400,401,403,404,422"` |
18+
19+
**Note:** _(*) marks required inputs_
20+
21+
## Outputs
22+
23+
`issues/add-labels` does not have any outputs at this time
24+
25+
## Example
26+
27+
Here is a very basic example of how to use the `issues/add-labels` composite action
28+
in a project (placeholders are used in place of real inputs):
29+
30+
```yaml
31+
run:
32+
example-job:
33+
# ...
34+
steps:
35+
# ...
36+
- name: Add labels to issue
37+
uses: bitwizeshift/actions-github/issues/add-labels@v1
38+
with:
39+
# Required inputs
40+
labels: LABELS
41+
42+
# Optional inputs
43+
issue-number: ISSUE_NUMBER
44+
owner: OWNER
45+
repo: REPO
46+
retries: RETRIES
47+
retry-exempt-status-codes: RETRY_EXEMPT_STATUS_CODES
48+
```

‎docs/issues-close.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Close issue
2+
3+
<!-- These docs are generated by a tool -->
4+
5+
A composite action for closing an issue.
6+
This requires `issues: write` permissions in order to work correctly.
7+
8+
## Inputs
9+
10+
| Name | Description | Default |
11+
|------|-------------|---------|
12+
| `issue-number` | The issue number to comment on | `"0"` |
13+
| `owner` | The repository owner | `""` |
14+
| `repo` | The repository | `""` |
15+
| `retries` | The number of times to try retrying | `"0"` |
16+
| `retry-exempt-status-codes` | The retry exempt status codes | `"400,401,403,404,422"` |
17+
| `state_reason` | The reason for the state-change | `"completed"` |
18+
19+
## Outputs
20+
21+
`issues/close` does not have any outputs at this time
22+
23+
## Example
24+
25+
Here is a very basic example of how to use the `issues/close` composite action
26+
in a project (placeholders are used in place of real inputs):
27+
28+
```yaml
29+
run:
30+
example-job:
31+
# ...
32+
steps:
33+
# ...
34+
- name: Close issue
35+
uses: bitwizeshift/actions-github/issues/close@v1
36+
with:
37+
# Optional inputs
38+
issue-number: ISSUE_NUMBER
39+
owner: OWNER
40+
repo: REPO
41+
retries: RETRIES
42+
retry-exempt-status-codes: RETRY_EXEMPT_STATUS_CODES
43+
state_reason: STATE_REASON
44+
```

‎docs/issues-create-comment.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Create comment on Issue
2+
3+
<!-- These docs are generated by a tool -->
4+
5+
A composite action that creates a comment on Github.
6+
Requires the `issues: write` permission to work.
7+
8+
## Inputs
9+
10+
| Name | Description | Default |
11+
|------|-------------|---------|
12+
| `body` (*) | The message to comment | _N/A_ |
13+
| `issue-number` | The issue number to comment on | `"0"` |
14+
| `owner` | The repository owner | `""` |
15+
| `repo` | The repository | `""` |
16+
| `retries` | The number of times to try retrying | `"0"` |
17+
| `retry-exempt-status-codes` | The retry exempt status codes | `"400,401,403,404,422"` |
18+
19+
**Note:** _(*) marks required inputs_
20+
21+
## Outputs
22+
23+
| Name | Description |
24+
|------|-------------|
25+
| `comment-id` | The ID of the created comment |
26+
| `comment-url` | A URL to the created comment |
27+
28+
## Example
29+
30+
Here is a very basic example of how to use the `issues/create-comment` composite action
31+
in a project (placeholders are used in place of real inputs):
32+
33+
```yaml
34+
run:
35+
example-job:
36+
# ...
37+
steps:
38+
# ...
39+
- name: Create comment on Issue
40+
id: create-comment-on-issue # only necessary if using this action's output(s)
41+
uses: bitwizeshift/actions-github/issues/create-comment@v1
42+
with:
43+
# Required inputs
44+
body: BODY
45+
46+
# Optional inputs
47+
issue-number: ISSUE_NUMBER
48+
owner: OWNER
49+
repo: REPO
50+
retries: RETRIES
51+
retry-exempt-status-codes: RETRY_EXEMPT_STATUS_CODES
52+
# ...
53+
- name: Uses "Create comment on Issue" Outputs
54+
uses: example-actions/use-create-comment-on-issue@v3 # illustrative
55+
with:
56+
use-comment-id: ${{ steps.create-comment-on-issue.outputs.comment-id }}
57+
use-comment-url: ${{ steps.create-comment-on-issue.outputs.comment-url }}
58+
```

‎docs/issues-create-or-comment.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Create issue or comment
2+
3+
<!-- These docs are generated by a tool -->
4+
5+
A composite action for getting either creating a Github issue, or commenting on
6+
an existing one, based on the author and the provided label(s), assignees, etc.
7+
This requires `issues: write` permissions in order to work correctly.
8+
9+
## Inputs
10+
11+
| Name | Description | Default |
12+
|------|-------------|---------|
13+
| `title` (*) | The title to use for the issue | _N/A_ |
14+
| `assignees` | A list of assignees to add, separated by newlines. | `""` |
15+
| `body` | The body text of the github issue | `""` |
16+
| `comment` | The comment to leave if an issue already exists | `"${{ inputs.body }}"` |
17+
| `labels` | A list of labels to add, separated by newlines. | `""` |
18+
| `owner` | The repository owner | `""` |
19+
| `repo` | The repository | `""` |
20+
| `retries` | The number of times to try retrying | `"3"` |
21+
| `retry-exempt-status-codes` | The retry exempt status codes | `"400,401,403,404,422"` |
22+
23+
**Note:** _(*) marks required inputs_
24+
25+
## Outputs
26+
27+
| Name | Description |
28+
|------|-------------|
29+
| `created-issue` | A boolean indicating whether a new issue was created |
30+
| `issue-number` | The number of the created issue |
31+
| `issue-url` | The HTTP URL of the newly created issue |
32+
33+
## Example
34+
35+
Here is a very basic example of how to use the `issues/create-or-comment` composite action
36+
in a project (placeholders are used in place of real inputs):
37+
38+
```yaml
39+
run:
40+
example-job:
41+
# ...
42+
steps:
43+
# ...
44+
- name: Create issue or comment
45+
id: create-issue-or-comment # only necessary if using this action's output(s)
46+
uses: bitwizeshift/actions-github/issues/create-or-comment@v1
47+
with:
48+
# Required inputs
49+
title: TITLE
50+
51+
# Optional inputs
52+
assignees: ASSIGNEES
53+
body: BODY
54+
comment: COMMENT
55+
labels: LABELS
56+
owner: OWNER
57+
repo: REPO
58+
retries: RETRIES
59+
retry-exempt-status-codes: RETRY_EXEMPT_STATUS_CODES
60+
# ...
61+
- name: Uses "Create issue or comment" Outputs
62+
uses: example-actions/use-create-issue-or-comment@v3 # illustrative
63+
with:
64+
use-created-issue: ${{ steps.create-issue-or-comment.outputs.created-issue }}
65+
use-issue-number: ${{ steps.create-issue-or-comment.outputs.issue-number }}
66+
use-issue-url: ${{ steps.create-issue-or-comment.outputs.issue-url }}
67+
```

‎docs/issues-create.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Create issue
2+
3+
<!-- These docs are generated by a tool -->
4+
5+
A composite action for creating a github issue.
6+
This requires `issues: write` permissions in order to work correctly.
7+
8+
## Inputs
9+
10+
| Name | Description | Default |
11+
|------|-------------|---------|
12+
| `title` (*) | The title to use for the issue | _N/A_ |
13+
| `assignees` | A list of assignees to add, separated by newlines. | `""` |
14+
| `body` | The body text of the github issue | `""` |
15+
| `labels` | A list of labels to add, separated by newlines. | `""` |
16+
| `owner` | The repository owner | `""` |
17+
| `repo` | The repository | `""` |
18+
| `retries` | The number of times to try retrying | `"3"` |
19+
| `retry-exempt-status-codes` | The retry exempt status codes | `"400,401,403,404,422"` |
20+
21+
**Note:** _(*) marks required inputs_
22+
23+
## Outputs
24+
25+
| Name | Description |
26+
|------|-------------|
27+
| `issue-number` | The number of the created issue |
28+
| `issue-url` | The HTTP URL of the newly created issue |
29+
30+
## Example
31+
32+
Here is a very basic example of how to use the `issues/create` composite action
33+
in a project (placeholders are used in place of real inputs):
34+
35+
```yaml
36+
run:
37+
example-job:
38+
# ...
39+
steps:
40+
# ...
41+
- name: Create issue
42+
id: create-issue # only necessary if using this action's output(s)
43+
uses: bitwizeshift/actions-github/issues/create@v1
44+
with:
45+
# Required inputs
46+
title: TITLE
47+
48+
# Optional inputs
49+
assignees: ASSIGNEES
50+
body: BODY
51+
labels: LABELS
52+
owner: OWNER
53+
repo: REPO
54+
retries: RETRIES
55+
retry-exempt-status-codes: RETRY_EXEMPT_STATUS_CODES
56+
# ...
57+
- name: Uses "Create issue" Outputs
58+
uses: example-actions/use-create-issue@v3 # illustrative
59+
with:
60+
use-issue-number: ${{ steps.create-issue.outputs.issue-number }}
61+
use-issue-url: ${{ steps.create-issue.outputs.issue-url }}
62+
```

0 commit comments

Comments
 (0)