|
2 | 2 |
|
3 | 3 | Trigger other workflows, display a link, and optionally wait for the result. |
4 | 4 |
|
5 | | -## Usage |
| 5 | +## Examples |
6 | 6 |
|
7 | | -### Inputs |
| 7 | +See [Usage](#usage) for full documentation. |
8 | 8 |
|
9 | | -| Name | Description | Required | Default | |
10 | | -| ------------ | -------------------------------------------------- | -------- | ------------------ | |
11 | | -| inputs | JSON object of inputs | No | {} | |
12 | | -| marker-input | Name of the downstream's input for upstream URL. | No | | |
13 | | -| owner | Repsitory owner name | No | Current owner | |
14 | | -| ref | Git reference | No | Current ref | |
15 | | -| repo | Repository name | No | Current repository | |
16 | | -| token | Personal access token | Yes | | |
17 | | -| wait | Whether to wait for conclusion | No | false | |
18 | | -| workflow | Workflow path in .github/workflows (e.g. main.yml) | Yes | |
| 9 | +### Same repository |
19 | 10 |
|
20 | | -### Outputs |
21 | | - |
22 | | -| Name | Description | |
23 | | -| ---------- | ------------------------------------ | |
24 | | -| conclusion | Workflow conclusion, if wait is true | |
25 | | -| run_id | Workflow run ID | |
26 | | - |
27 | | -### Marker step |
28 | | - |
29 | | -The Github API does not provide a direct association between a workflow dispatch |
30 | | -and the subsequent workflow run. For greater robustness in determining the |
31 | | -relationship, the upstream URL can be used as an input. _The downstream workflow |
32 | | -must use that value as the name of a step._ (See [example](#marker-step-1).) |
| 11 | +**upstream.yml** |
33 | 12 |
|
34 | | -### Personal access token |
| 13 | +```yml |
| 14 | +job: |
| 15 | + example: |
| 16 | + steps: |
| 17 | + - use: pauldraper/[email protected] |
| 18 | + with: |
| 19 | + inputs: '{"color": "blue"}' |
| 20 | + workflow: downstream.yml |
| 21 | +``` |
35 | 22 |
|
36 | | -A personal access token is required with read/write permissions for actions on |
37 | | -the downstream repo. (Note: The default `GITHUB_TOKEN` does not have sufficient |
38 | | -permissions.) See |
39 | | -[Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). |
| 23 | +**downstream.yml** |
40 | 24 |
|
41 | | -## Examples |
| 25 | +```yml |
| 26 | +on: [workflow_dispatch] |
| 27 | +``` |
42 | 28 |
|
43 | | -### Basic |
| 29 | +### Different repository, and wait for finish |
44 | 30 |
|
45 | 31 | **upstream.yml** |
46 | 32 |
|
|
51 | 37 | - use: pauldraper/[email protected] |
52 | 38 | with: |
53 | 39 | inputs: '{"color": "blue"}' |
54 | | - owner: example |
55 | 40 | ref: refs/head/main |
56 | | - repo: example |
57 | | - token: "${{ secrets.GH_TOKEN }}" |
| 41 | + repo: example/example |
| 42 | + token: ${{ secrets.GH_TOKEN }} |
| 43 | + wait: "true" |
58 | 44 | workflow: downstream.yml |
59 | 45 | ``` |
60 | 46 |
|
|
75 | 61 | - use: pauldraper/[email protected] |
76 | 62 | with: |
77 | 63 | marker-input: upstream-url |
78 | | - token: "${{ secrets.GH_TOKEN }}" |
| 64 | + workflow: downstream.yml |
79 | 65 | ``` |
80 | 66 |
|
81 | 67 | **downstream.yml** |
|
84 | 70 | jobs: |
85 | 71 | example: |
86 | 72 | steps: |
87 | | - - if: "${{ inputs.upstream-url }}" |
88 | | - name: "${{ inputs.upstream-url }}" |
| 73 | + - if: ${{ inputs.upstream-url }} |
| 74 | + name: ${{ inputs.upstream-url }} |
89 | 75 | run: |
90 | 76 | echo 'Started by [${{ inputs.upstream-url }}](${{ inputs.upstream-url |
91 | 77 | }})' >> "$GITHUB_STEP_SUMMARY" |
|
95 | 81 | upstream-url: |
96 | 82 | description: URL of upstream run |
97 | 83 | ``` |
| 84 | +
|
| 85 | +## Usage |
| 86 | +
|
| 87 | +### Inputs |
| 88 | +
|
| 89 | +| Name | Description | Required | Default | |
| 90 | +| ------------ | -------------------------------------------------- | -------- | -------------------------------- | |
| 91 | +| inputs | JSON object of inputs | No | `{}` | |
| 92 | +| marker-input | Name of the downstream's input for upstream URL. | No | `` | |
| 93 | +| owner | Repsitory owner name | No | `${{ github.repository_owner }}` | |
| 94 | +| ref | Git reference | No | `${{ github.ref }}` | |
| 95 | +| repo | Repository name | No | `${{ github.repository }}` | |
| 96 | +| token | Personal access token | No | `${{ github.token }}` | |
| 97 | +| wait | Whether to wait for conclusion | No | `false` | |
| 98 | +| workflow | Workflow path in .github/workflows (e.g. main.yml) | Yes | `` | |
| 99 | + |
| 100 | +### Outputs |
| 101 | + |
| 102 | +| Name | Description | |
| 103 | +| ---------- | ------------------------------------ | |
| 104 | +| conclusion | Workflow conclusion, if wait is true | |
| 105 | +| run_id | Workflow run ID | |
| 106 | + |
| 107 | +### Marker step |
| 108 | + |
| 109 | +The Github API does not provide a direct association between a workflow dispatch |
| 110 | +and the subsequent workflow run. For greater robustness in determining the |
| 111 | +relationship, the upstream URL can be used as an input. The downstream workflow |
| 112 | +must use that value as the name of a step, so that the action can find it. (See |
| 113 | +[example](#marker-step-1).) |
| 114 | + |
| 115 | +### Token |
| 116 | + |
| 117 | +`GITHUB_TOKEN` must have read/write actions permissions. See |
| 118 | +[Permissions for the `GITHUB_TOKEN`](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). |
| 119 | + |
| 120 | +When starting workflows in other repos, you must create a personal access token |
| 121 | +and provide it as the `token` input. See |
| 122 | +[Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) |
| 123 | +and |
| 124 | +[Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets). |
0 commit comments