GitHub

Sifflet brings its lineage into your GitHub pull requests. When a pull request changes dbt models, the dbt Impact Analysis GitHub Action asks Sifflet which tables and dashboards depend on these models, and posts the list as a pull request comment, so reviewers see the impact of a change before it reaches production.

Sifflet doesn't connect to GitHub and doesn't import anything from it: the action runs in your GitHub Actions workflows and calls the Sifflet API.

Permissions Required

The integration uses two tokens: a Sifflet access token, which the action uses to read lineage from Sifflet, and the GitHub token of the workflow, which the action uses to read the pull request and post the comment.

pull-requests: write is the only write permission: the action uses it only to add a comment.

The action sends Sifflet the names of the changed dbt models and of their dbt projects, and the path of the pull request (<OWNER>/<REPOSITORY>/pull/<NUMBER>), which Sifflet records with each analyzed model. It doesn't send any code.

Requirements

Required Roles for Setup

• In GitHub, the right to edit workflows and to create Actions secrets in the repository (or in the organization, to share the secret between repositories).
• In Sifflet, the Admin role to create the access token. See Access Control.

Supported Versions and Editions

• Repositories hosted on GitHub.com. GitHub Enterprise Server isn't supported: the action always calls the GitHub.com API.
• Linux runners, since the action runs as a Docker container action. GitHub-hosted ubuntu-* runners work.

Network Access

The connection goes from your GitHub Actions runners to Sifflet:

• The runner must reach your Sifflet API at https://<TENANT>.siffletdata.com/api, and pull the action image from the public.ecr.aws registry.
• If your Sifflet instance restricts API access to known IP ranges, run the action on self-hosted runners whose IP addresses are allowed.

Other Prerequisites

• A dbt Core or dbt Cloud source in Sifflet for each dbt project of the repository. The name in the dbt_project.yml file must match the dbt project name known to Sifflet.
• Each dbt project of the repository has a dbt_project.yml file in the directory of its models or in a parent directory.

Connect Sifflet to GitHub

Step 1: Create a Sifflet Access Token

1. In Sifflet, go to Settings > Access Tokens and click New Access Token.
2. Enter a name (for example github-dbt-impact-analysis), select the Viewer role, and click Generate.
3. Copy the token. Sifflet shows it only once. It expires after 24 months by default: see Access Tokens to set another expiration and to rotate it.
4. In GitHub, add the token as an Actions secret named SIFFLET_API_TOKEN:
   • for one repository, go to Settings > Secrets and variables > Actions in the repository and click New repository secret (see Creating secrets for a repository);
   • for several repositories, create it as an organization secret instead (see Creating secrets for an organization).

Step 2: Add the dbt Impact Analysis Action to Your Workflows

1. In your repository, create a workflow file, for example .github/workflows/sifflet-dbt-impact-analysis.yml (see Creating your first workflow). You can also start from the GitHub Marketplace page of the action.

2. Paste the following workflow. Replace <TENANT> with the name of your Sifflet instance.

   YAML

   on: [pull_request]
   
   permissions:
     contents: read
     pull-requests: write
   
   jobs:
     dbt_impact_analysis_job:
       runs-on: ubuntu-latest
       name: Impact analysis of dbt changes
       steps:
         - name: dbt impact analysis
           uses: siffletdata/dbt-impact-analysis-action@v1
           with:
             git-provider-token: ${{ secrets.GITHUB_TOKEN }}
             sifflet-instance-url: https://<TENANT>.siffletdata.com
             sifflet-api-token: ${{ secrets.SIFFLET_API_TOKEN }}
             impacted-asset-types: 'DASHBOARD, DATASET'

3. Adjust the inputs:

   Input	Required	Description	Example
   git-provider-token	Yes	The GitHub token the action uses to read the pull request and comment on it. Keep ${{ secrets.GITHUB_TOKEN }}, with the permissions block of the workflow above.	${{ secrets.GITHUB_TOKEN }}
   sifflet-instance-url	Yes	The URL of your Sifflet instance, without /api and without a trailing slash	https://acme.siffletdata.com
   sifflet-api-token	Yes	The Sifflet access token created in step 1	${{ secrets.SIFFLET_API_TOKEN }}
   impacted-asset-types	No	The types of downstream assets to list in the report, separated by a comma and a space: DATASET, DASHBOARD. Empty (default): all of them.	'DASHBOARD, DATASET'
   impacted-tags	No	Only list downstream assets that have at least one of these Sifflet tags, separated by a comma and a space. Empty (default): no tag filter.	'pii, finance'

4. Commit the workflow file to your default branch.

The action now runs on every pull request. To check the setup, open a pull request that changes a dbt model: the action posts a Sifflet Impact Report comment. For what the report contains and how the action finds the changed models, see dbt Impact Analysis GitHub Action.

Troubleshooting

The Report Says a Model Is Not Found in Sifflet

• Symptom: the comment contains <MODEL_NAME> not found in Sifflet.
• Cause: Sifflet doesn't find exactly one dbt model with this name in a dbt project whose name matches the name of the closest dbt_project.yml file. Either the model doesn't exist in Sifflet yet (new model, or dbt source not refreshed since), or several dbt sources in Sifflet contain the same project and model.
• Fix:
  1. Check that the name in dbt_project.yml matches the project of your dbt source in Sifflet: see Other Prerequisites.
  2. For a new model, run your dbt job and refresh the dbt source in Sifflet, then push a new commit to the pull request.
  3. If several dbt sources in Sifflet contain the same dbt project (for example one source per dbt target), the action can't choose between them and skips the model: see Limitations.

The Action Fails Without Posting a Comment

• Symptom: the job fails with An error occurred: Invalid Github token for repository <OWNER>/<REPOSITORY>, or with Error occurred when calling the Sifflet API for DBT model <MODEL_NAME> and status code 401 or 403.
• Cause: the GitHub token can't access the repository or lacks the permissions of the workflow, or the Sifflet access token is wrong, expired, or doesn't have the Viewer role.
• Fix:
  1. Check the permissions block of the workflow and the git-provider-token input: see Step 2.
  2. Check the SIFFLET_API_TOKEN secret, or create a new access token: see Step 1.