Skip to content

Commit

Permalink
Update branch protection documentation
Browse files Browse the repository at this point in the history
The contexts attribute can contain multiple variations of strings that
are not documented clearly. These variations differ greatly depending on
the usecase, including:
- Typical usage with name/id
- Appending matrix value(s)
- Utilising reusable workflows.
  • Loading branch information
LiamMacP committed Jan 9, 2024
1 parent 5752b25 commit 7d9f22f
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 0 deletions.
5 changes: 5 additions & 0 deletions website/docs/r/branch_protection.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,11 @@ The following arguments are supported:
* `strict`: (Optional) Require branches to be up to date before merging. Defaults to `false`.
* `contexts`: (Optional) The list of status checks to require in order to merge into this branch. No status checks are required by default.

~> Note: This attribute can contain multiple string patterns.
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/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname) is defaulted to.
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/using-jobs/using-a-matrix-for-your-jobs#using-a-matrix-strategy") for more information.
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.

### Required Pull Request Reviews

`required_pull_request_reviews` supports the following arguments:
Expand Down
6 changes: 6 additions & 0 deletions website/docs/r/branch_protection_v3.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,12 @@ The following arguments are supported:

* `strict`: (Optional) Require branches to be up to date before merging. Defaults to `false`.
* `contexts`: [**DEPRECATED**] (Optional) The list of status checks to require in order to merge into this branch. No status checks are required by default.

~> Note: This attribute can contain multiple string patterns.
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/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname) is defaulted to.
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/using-jobs/using-a-matrix-for-your-jobs#using-a-matrix-strategy") for more information.
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.

* `checks`: (Optional) The list of status checks to require in order to merge into this branch. No status checks are required by default. Checks should be strings containing the context and app_id like so "context:app_id".

### Required Pull Request Reviews
Expand Down

0 comments on commit 7d9f22f

Please sign in to comment.