Skip to content
Common Fate
Docs Granted

Continuous Integration

Validating policies in your CI workflows allows you to check for potential policy issues each time a change is made to your policy source code. Common Fate policy validation can be run in CI platforms such as GitHub Actions, GitLab, and BuildKite.

An example policy validation check in GitHub Actions.

If you use GitHub Actions, our Cedar Policy Validation Action will show annotations on Pull Requests, indicating where issues are in your policy source code.

Annotations in GitHub Actions showing where issues are.

Prerequisites

If you’re running a BYOC (“Bring-Your-Own-Cloud”) deployment of Common Fate in your own AWS account, you’ll need to be on v1.31.0 or later of the common-fate/common-fate-deployment/aws Terraform module.

Policy validation in CI

Choose a tab below based on your CI provider.

To validate policies using GitHub Actions, you can use the Download Cedar Schema Action to download the latest Cedar schema, and use the Validate Cedar Policies Action to validate against the schema.

Here’s an example workflow.

name: Test


on:
  push:


jobs:
  cedar:
    name: Cedar
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4


      - name: Download Cedar Schema
        uses: common-fate/download-cedar-schema-action@v1
        with:
          deployment-url: https://commonfate.example.com # replace this with your Common Fate API URL
          oidc-client-id: abcdefGHIJKL12345678 # replace this with your Client ID
          oidc-client-secret: ${{ secrets.CF_OIDC_CLIENT_SECRET }}
          oidc-issuer: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abcdeFGH # replace this with your Issuer
          save-schema-file-to: common-fate.cedarschema.json


      - name: Validate Policies
        uses: common-fate/cedar-validate-action@v1
        with:
          schema-file: common-fate.cedarschema.json
          policy-files: "**/*.cedar"

As shown above, the workflow requires a few configuration variables to tell the CLI where Common Fate is running (api-url), and how to authenticate to it (oidc-client-id, oidc-client-secret, oidc-issuer). You can obtain api-url and oidc-issuer from your Terraform provider configuration block:

provider "commonfate" {
  api_url            = "https://commonfate.example.com" # corresponds to 'deployment-url' in the workflow
  oidc_issuer        = "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abcdeFGH"  # corresponds to 'oidc-issuer' in the workflow
}

You can look up the Read-Only client credentials for oidc-client-id and oidc-client-secret by finding it in the deployment outputs following our guide here. Save the OIDC client secret as a GitHub Actions Secret with the name CF_OIDC_CLIENT_SECRET to keep it out of your source code. The Read-Only client has read access to the policy and configuration APIs but cannot be used for destructive actions.

Store the OIDC Client Secret as a secret, with the key CF_OIDC_CLIENT_SECRET

Access testing in CI

Choose a tab below based on your CI provider.

To run access tests using GitHub Actions, you can use the Install Common Fate CLI Action to install the cf CLI, and then run cf tests run -f tests.yml.

You’ll need to add an access test file into your Common Fate configuration repository first.

Here’s an example workflow.

name: Test


on:
  push:


jobs:
  access:
    name: Access Testing
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4


      - name: Install Common Fate CLI
        uses: common-fate/install-cli-action@v1
        with:
          oidc-client-id: abcdefGHIJKL12345678 # replace this with your Client ID
          oidc-client-secret: ${{ secrets.CF_OIDC_CLIENT_SECRET }}
          oidc-issuer: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abcdeFGH # replace this with your Issuer
          api-url: https://commonfate.example.com # replace this with your Common Fate API URL


      - name: Run Access Tests
        run: cf tests run -f tests.yml

As shown above, the workflow requires a few configuration variables to tell the CLI where Common Fate is running (api-url), and how to authenticate to it (oidc-client-id, oidc-client-secret, oidc-issuer). You can obtain api-url and oidc-issuer from your Terraform provider configuration block:

provider "commonfate" {
  api_url            = "https://commonfate.example.com" # corresponds to 'deployment-url' in the workflow
  oidc_issuer        = "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abcdeFGH"  # corresponds to 'oidc-issuer' in the workflow
}

You can look up the Read-Only client credentials for oidc-client-id and oidc-client-secret by finding it in the deployment outputs following our guide here. Save the OIDC client secret as a GitHub Actions Secret with the name CF_OIDC_CLIENT_SECRET to keep it out of your source code. The Read-Only client has read access to the policy and configuration APIs but cannot be used for destructive actions.

Store the OIDC Client Secret as a secret, with the key CF_OIDC_CLIENT_SECRET

After completing this guide, you should see access tests being executed in GitHub Actions as shown below.

An example GitHub Actions access tests run