Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kosli-dev/control-actions


https://github.com/kosli-dev/control-actions

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

          
# Code Review GitHub Actions



This repository contains GitHub Actions for evaluating code review controls in Kosli. These actions help ensure that all commits in a release have been properly reviewed before deployment.



## Overview



The repository provides three actions:



1. **Create Code Review Attestation Type** - Sets up a custom attestation type for code review evaluations

2. **Code Review** - Evaluates code review attestations for commits between two git references

3. **Override Pull Request** - override a missing or non-compliant pull request attestation



## Prerequisites



1. **Kosli Account**: You need a Kosli account and API token for both of these actions



## Actions



### 1. Create Code Review Attestation Type



This action creates a custom attestation type in Kosli for storing code review evaluation results.

The action can be run in a manually-triggered workflow or be part of your regular workflow (e.g. on push).



The custom attestation type created by this action is required by the code-review action described below.



#### Usage



```yaml

- name: Create Code Review Attestation Type

  uses: kosli-dev/control-actions/create-code-review-type@v1

  with:

    kosli_api_token: ${{ secrets.KOSLI_API_TOKEN }}

    kosli_org: your-organization-name

    kosli_cli_version: v2.11.20

    kosli_host_name: https://app.kosli.com  # Optional, defaults to https://app.kosli.com

```



#### Inputs



| Input | Description | Required | Default |

|-------|-------------|----------|---------|

| `kosli_api_token` | The Kosli API token for authorization | Yes | - |

| `kosli_org` | The Kosli organization name | Yes | - |

| `kosli_cli_version` | Kosli CLI version to use | Yes | - |

| `kosli_host_name` | The Kosli host name | No | `https://app.kosli.com` |



#### What it does



- Sets up the Kosli CLI with the specified version

- Creates a custom attestation type called `code-review` with a schema that validates:

  - `commit`: 40-character SHA hash

  - `pass`: boolean indicating if the commit passed review

  - `reason`: string explaining the result

  - `attestation_url`: optional URL to the attestation



### 2. Code Review



## Prerequisites



1. **Git History**: The repository must have sufficient git history to compare releases (set `fetch-depth: 0` in `actions/checkout`)

2. **Pull Request Attestations**: Your development flow should have pull request attestations for each commit on the main branch

3. **Custom Attestation Type**: The code review attestation type must be created before running evaluations



**How the evaluation works:**



The action evaluates each commit in your release (between the base reference and the current release reference) to determine if it meets the code review requirements. A commit passes the review control if:



1. **The commit has an associated pull-request attestation with an associated pull request or has an override** - This means the code was reviewed through a pull request process, Or,

   the commit has an override attestation associated with it which marks a manual approval/exemption.

2. **The pull request meets the review criteria** - The pull request is considered passing if:

   - It has at least two different reviewers, OR

   - It has at least one reviewer who is not a committer in the branch being merged



If every commit in your release passes these criteria, the overall evaluation is marked as **passed**. If any commit fails to meet the requirements, the evaluation is marked as **failed**.



The action then reports these evaluation results to Kosli as an attestation.



#### Usage



```yaml

- name: Evaluate Code Review Control

  uses: kosli-dev/control-actions/code-review@v1

  with:

    base_ref: v1.0.0

    release_ref: v1.1.0

    kosli_api_token: ${{ secrets.KOSLI_API_TOKEN }}

    kosli_org: your-organization-name

    kosli_search_flow_name: development

    kosli_code_review_attestation_type: code-review

    kosli_code_review_attestation_name: release-code-review

    kosli_code_review_flow_name: releases

    kosli_code_review_trail_name: v1.1.0

    kosli_host_name: https://app.kosli.com  # Optional

```



#### Inputs



| Input | Description | Required | Default |

|-------|-------------|----------|---------|

| `base_ref` | The base git ref (e.g., previous release tag) | Yes | - |

| `release_ref` | The git ref being released | Yes | - |

| `kosli_api_token` | The Kosli API token for authorization | Yes | - |

| `kosli_org` | The Kosli organization name | Yes | - |

| `kosli_search_flow_name` | The Kosli flow where source attestations are stored | Yes | - |

| `kosli_code_review_attestation_type` | The attestation type for reporting code review results | Yes | - |

| `kosli_code_review_attestation_name` | The attestation name for reporting code review results | Yes | - |

| `kosli_code_review_flow_name` | The flow name to report code review attestations to | Yes | - |

| `kosli_code_review_trail_name` | The trail name to report code review attestations to | Yes | - |

| `kosli_host_name` | The Kosli host name | No | `https://app.kosli.com` |



#### What it does



1. **Gets commit list**: Retrieves all commits between `base_ref` and `release_ref`

2. **Fetches attestations**: Queries Kosli API for pull request attestations for each commit

3. **Evaluates reviews**: Checks if each commit passes the code-review control

4. **Reports results**: Creates a new attestation in the specified flow/trail with evaluation results



#### Output



The action generates:

- `attestations_evidence.json`: Raw attestation data from Kosli

- `evaluation_results.json`: Processed evaluation results

- A new attestation in the specified Kosli flow/trail with the evaluation summary



## Complete Workflow Example



Here's a complete example of how to use both actions in a release workflow:



```yaml

name: Release with Code Review Control



on:

  push:

    tags:

      - 'v*'



jobs:

  setup:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout code

        uses: actions/checkout@v4

        with:

          fetch-depth: 0  # Important: fetch all history for git operations



      - name: Create Code Review Attestation Type

        uses: kosli-dev/control-actions/create-code-review-type@main

        with:

          kosli_api_token: ${{ secrets.KOSLI_API_TOKEN }}

          kosli_org: my-organization

          kosli_cli_version: v2.11.19



  evaluate-code-review:

    runs-on: ubuntu-latest

    needs: setup

    steps:

      - name: Checkout code

        uses: actions/checkout@v4

        with:

          fetch-depth: 0



      - name: Get previous release tag

        id: previous_release

        run: |

          PREVIOUS_TAG=$(git tag --sort=-version:refname | head -n 2 | tail -n 1)

          echo "tag=$PREVIOUS_TAG" >> $GITHUB_OUTPUT



      - name: Evaluate Code Review Control

        uses: kosli-dev/control-actions/code-review@main

        with:

          base_ref: ${{ steps.previous-tag.outputs.previous_tag }}

          release_ref: ${{ github.ref_name }}

          kosli_api_token: ${{ secrets.KOSLI_API_TOKEN }}

          kosli_org: my-organization

          kosli_search_flow_name: development

          kosli_code_review_attestation_type: code-review

          kosli_code_review_attestation_name: release-code-review

          kosli_code_review_flow_name: releases

          kosli_code_review_trail_name: ${{ github.ref_name }}

```



### 2. Override Pull Request attestation



This action allows you to override a specific `pull_request` attestation to mark it as compliant.



#### Usage



```yaml

- name: Override pull request attestation

  uses: kosli-dev/control-actions/override-pull-request@v1

  with:

    kosli_api_token: ${{ secrets.KOSLI_API_TOKEN }}

    kosli_org: your-organization-name

    kosli_flow_name: build_flow

    kosli_trail_name: 5b33764ac5d08a7945afd792476dd139afadc376

    attestation_name: pull-request

    override_reason: "looks good to me!"

    override_compliance: true

    kosli_host_name: https://app.kosli.com  # Optional, defaults to https://app.kosli.com

```



#### Inputs



| Input | Description | Required | Default |

|-------|-------------|----------|---------|

| `kosli_api_token` | The Kosli API token for authorization | Yes | - |

| `kosli_org` | The Kosli organization | Yes | - |

| `kosli_flow_name` | The Kosli flow for the pull-request override | Yes | - |

| `kosli_trail_name` | The Kosli trail for the pull-request override | Yes | - |

| `attestation_name` | The name of the pull_request attestation we want to override | Yes | - |

| `override_reason` | The reason for the override | Yes | - |

| `override_compliance` | Compliance value for override | Yes | - |

| `kosli_host_name` | The Kosli host name | No | `https://app.kosli.com` |



#### What it does



- It creates a new `override` attestation in the specified flow and trail for the attestation_name provided.

- The override attestation causes a new compliance calculation of the trail to consider the override effect.



#### Next steps



After overriding missing/non-compliant individual pull_request attestations, you need to re-attest the code-review attestation (e.g. re-run the code-review workflow) to produce an updated code-review attestation that takes the overrides into account.



## Troubleshooting



### Common Issues



1. **No commits found**: Ensure `base_ref` exists and `fetch-depth: 0` is set in checkout

2. **API errors**: Check that the Kosli API token is valid and has proper permissions

3. **Custom attestation type not found**: Run the create action before the evaluation action



### Debugging



The actions generate detailed logs for debugging:

- Check the action logs for error messages