Skip to content

Commit 75f7685

Browse files
ViacheslavKudinovViacheslavKudinov
authored
Merge pull request #40 from vk-or/doc/branch-protection-status-check
Tune status check doc
2 parents 050b64b + 4c9f930 commit 75f7685

1 file changed

Lines changed: 199 additions & 36 deletions

File tree

‎website/docs/r/branch_protection.html.markdown‎

Lines changed: 199 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,200 @@ resource "github_team_repository" "example" {
8787
}
8888
```
8989

90+
## Example Usage - Status Check with job_name and/or job_id
91+
92+
Given the following workflow:
93+
94+
```yaml
95+
...
96+
jobs:
97+
build:
98+
name: Build and Test
99+
runs-on: ubuntu-latest
100+
steps:
101+
...
102+
test:
103+
runs-on: ubuntu-latest
104+
steps:
105+
...
106+
```
107+
108+
The value to use in `contexts` would be `Build and Test` (the job name) for the first job, and `test` (the job_id) for the second job.
109+
110+
~> **Note:** When a job has a `name` attribute, GitHub uses the **name** as the status check context. When a job doesn't have a `name`, GitHub uses the `job_id`. You must use whichever one GitHub reports as the status check context.
111+
112+
```hcl
113+
resource "github_branch_protection" "example" {
114+
repository_id = github_repository.example.node_id
115+
pattern = "main"
116+
117+
required_status_checks {
118+
contexts = [
119+
"Build and Test", # Uses job name because name is specified
120+
"test", # Uses job_id because no name is specified
121+
]
122+
}
123+
}
124+
```
125+
## Example Usage - Status Check with Matrix Jobs
126+
For example, given the following workflow:
127+
```yaml
128+
...
129+
jobs:
130+
example_matrix:
131+
name: Example Matrix
132+
strategy:
133+
matrix:
134+
version: [10, 12, 14]
135+
os: [ubuntu-latest, windows-latest]
136+
...
137+
```
138+
Since the job has a `name` attribute, you must use the job name (not the job id). The values to use in `contexts` would be:
139+
- Example Matrix (10, ubuntu-latest)
140+
- Example Matrix (10, windows-latest)
141+
- Example Matrix (12, ubuntu-latest)
142+
- Example Matrix (12, windows-latest)
143+
- Example Matrix (14, ubuntu-latest)
144+
- Example Matrix (14, windows-latest)
145+
146+
```hcl
147+
resource "github_branch_protection" "example" {
148+
repository_id = github_repository.example.node_id
149+
pattern = "main"
150+
required_status_checks {
151+
contexts = [
152+
"Example Matrix (10, ubuntu-latest)",
153+
"Example Matrix (10, windows-latest)",
154+
"Example Matrix (12, ubuntu-latest)",
155+
"Example Matrix (12, windows-latest)",
156+
"Example Matrix (14, ubuntu-latest)",
157+
"Example Matrix (14, windows-latest)",
158+
]
159+
}
160+
}
161+
```
162+
163+
## Example Usage - Status Check with Matrix Jobs (No Job Name)
164+
165+
If the workflow does **not** have a `name` attribute:
166+
```yaml
167+
...
168+
jobs:
169+
example_matrix:
170+
strategy:
171+
matrix:
172+
version: [10, 12, 14]
173+
os: [ubuntu-latest, windows-latest]
174+
...
175+
```
176+
Since there's no `name` attribute, you must use the `job_id`. The values to use in `contexts` would be:
177+
- example_matrix (10, ubuntu-latest)
178+
- example_matrix (10, windows-latest)
179+
- example_matrix (12, ubuntu-latest)
180+
- example_matrix (12, windows-latest)
181+
- example_matrix (14, ubuntu-latest)
182+
- example_matrix (14, windows-latest)
183+
184+
```hcl
185+
resource "github_branch_protection" "example" {
186+
repository_id = github_repository.example.node_id
187+
pattern = "main"
188+
required_status_checks {
189+
contexts = [
190+
"example_matrix (10, ubuntu-latest)",
191+
"example_matrix (10, windows-latest)",
192+
"example_matrix (12, ubuntu-latest)",
193+
"example_matrix (12, windows-latest)",
194+
"example_matrix (14, ubuntu-latest)",
195+
"example_matrix (14, windows-latest)",
196+
]
197+
}
198+
}
199+
```
200+
201+
## Example Usage - Status Check with Reusable Workflows
202+
203+
When using reusable workflows, the status check context follows the pattern: `<calling_workflow_job> / <called_workflow_job>`.
204+
If the caller or called workflow job has a `name` attribute, use the job name. If it doesn't have a `name` attribute, use the `job_id`.
205+
206+
Given the following caller workflow (`.github/workflows/caller.yml`):
207+
```yaml
208+
jobs:
209+
call-workflow:
210+
name: Call Reusable Workflow
211+
uses: ./.github/workflows/reusable.yml
212+
```
213+
214+
And the reusable workflow (`.github/workflows/reusable.yml`):
215+
```yaml
216+
jobs:
217+
build:
218+
name: Build Application
219+
runs-on: ubuntu-latest
220+
steps:
221+
...
222+
test:
223+
runs-on: ubuntu-latest
224+
steps:
225+
...
226+
```
227+
228+
Since both the caller job and the first reusable job have `name` attributes, use both names. The second job in the reusable workflow has no name, so use its `job_id`:
229+
230+
```hcl
231+
resource "github_branch_protection" "example" {
232+
repository_id = github_repository.example.node_id
233+
pattern = "main"
234+
required_status_checks {
235+
contexts = [
236+
"Call Reusable Workflow / Build Application", # caller name / reusable job name
237+
"Call Reusable Workflow / test", # caller name / reusable job_id
238+
]
239+
}
240+
}
241+
```
242+
243+
## Example Usage - Status Check with Reusable Workflows (No Job Names)
244+
245+
If the workflows do **not** have `name` attributes:
246+
247+
Caller workflow (`.github/workflows/caller.yml`):
248+
```yaml
249+
jobs:
250+
call-workflow:
251+
uses: ./.github/workflows/reusable.yml
252+
```
253+
254+
Reusable workflow (`.github/workflows/reusable.yml`):
255+
```yaml
256+
jobs:
257+
build:
258+
runs-on: ubuntu-latest
259+
steps:
260+
...
261+
test:
262+
runs-on: ubuntu-latest
263+
steps:
264+
...
265+
```
266+
267+
Use the `job_id` for both the caller and the reusable workflow jobs:
268+
269+
```hcl
270+
resource "github_branch_protection" "example" {
271+
repository_id = github_repository.example.node_id
272+
pattern = "main"
273+
required_status_checks {
274+
contexts = [
275+
"call-workflow / build", # caller job_id / reusable job_id
276+
"call-workflow / test", # caller job_id / reusable job_id
277+
]
278+
}
279+
}
280+
```
281+
282+
~> **Note:** For multi-level reusable workflows, the pattern extends: `<workflow1_job> / <workflow2_job> / <workflow3_job>`.
283+
90284
## Argument Reference
91285

92286
The following arguments are supported:
@@ -112,42 +306,11 @@ The following arguments are supported:
112306
* `strict`: (Optional) Require branches to be up to date before merging. Defaults to `false`.
113307
* `contexts`: (Optional) The list of status checks to require in order to merge into this branch. No status checks are required by default.
114308

115-
~> **Note:** This attribute can contain multiple string patterns.
116-
If specified, usual value is the [job name](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname). Otherwise, the [job id](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_id) is defaulted to.
117-
For example, given the following workflow:
118-
```yaml
119-
...
120-
jobs:
121-
build:
122-
name: Build and Test
123-
runs-on: ubuntu-latest
124-
steps:
125-
...
126-
test:
127-
runs-on: ubuntu-latest
128-
steps:
129-
...
130-
```
131-
The value to use in `contexts` would be either `Build and Test` or `build` for the first job, and `test` for the second job.
132-
For workflows that use matrixes, append the matrix name to the value using the following pattern `(<matrix_value>[, <matrix_value>])`. Matrixes should be specified based on the order of matrix properties in the workflow file. See [GitHub Documentation](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations?versionId=free-pro-team%40latest&productId=actions&restPage=how-tos%2Cwrite-workflows#adding-a-matrix-strategy-to-your-workflow-job) for more information.
133-
For example, given the following workflow:
134-
```yaml
135-
jobs:
136-
example_matrix:
137-
strategy:
138-
matrix:
139-
version: [10, 12, 14]
140-
os: [ubuntu-latest, windows-latest]
141-
```
142-
The values to use in `contexts` would be any of the following six options:
143-
- `example_matrix (10, ubuntu-latest)`
144-
- `example_matrix (10, windows-latest)`
145-
- `example_matrix (12, ubuntu-latest)`
146-
- `example_matrix (12, windows-latest)`
147-
- `example_matrix (14, ubuntu-latest)`
148-
- `example_matrix (14, windows-latest)`
149-
or combinations thereof.
150-
For workflows that use reusable workflows, the pattern is `<initial_workflow.jobs.job.[name/id]> / <reused-workflow.jobs.job.[name/id]>`. This can extend multiple levels.
309+
~> **Note:** This attribute can contain multiple string patterns representing GitHub Actions workflow job status checks.
310+
If a job has a [`name`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname) attribute, use the job name as the context value.
311+
If a job does **not** have a `name` attribute, use the [`job_id`](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_id) as the context value.
312+
Append the matrix values to the job name or job_id using the pattern: `<job_name_or_id> (<matrix_value>, <matrix_value>)`. For example: `Example Matrix (10, ubuntu-latest)`. See the examples above and [GitHub Documentation](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs) for more information.
313+
Use the pattern: `<caller_job_name_or_id> / <called_job_name_or_id>`. Apply the `name` vs `job_id` rule to both the caller and called workflow jobs. For multi-level reusable workflows, extend the pattern with additional levels separated by ` / `. See the examples above for more information.
151314

152315
### Required Pull Request Reviews
153316

0 commit comments

Comments
 (0)