Add impact analysis in GitHub
For existing users, the dbt-action
is no longer maintained and is deprecated eventually. Atlan strongly recommends migrating to the atlan-action
. Refer to How to migrate from dbt to Atlan action to learn more and complete the migration.
If you have ever changed a dbt model only to find out later that it broke a downstream table or dashboard, Atlan provides a GitHub Action to help you out.
This action places Atlan's impact analysis right into your pull request. So, you can view the potential downstream impact of your changes before merging the pull request.
Prerequisites
- Before running the action, you need to create an Atlan API token or configure an OAuth client.
- You also need to assign a persona to the API token and add a metadata policy that provides the requisite permissions on assets for the Atlan dbt action to work. For example, you can add the following permissions:
- dbt - Read and Update
- Materialized layer, such as Snowflake - Read and Update
- Any downstream connections, such as Microsoft Power BI - Read only
- When a pull request with changes to one or more dbt models is merged, the Atlan dbt action links the pull request as a resource to the assets in Atlan. To make sure that the pull request is linked as a resource, you need to assign the right persona with requisite permissions to the API token.
- You need to configure the default
GITHUB_TOKEN
permissions. Grant Read and write permissions to theGITHUB_TOKEN
in your repository to enable theatlan-action
to seamlessly add or update comments on pull requests. Refer to GitHub documentation to learn more.
Configure the action
To set up the Atlan action in GitHub:
- Create repository secrets in your repository:
ATLAN_INSTANCE_URL
with the URL of your Atlan instance.ATLAN_API_TOKEN
with the value of the API token.
- Add the GitHub Action to your workflow:
-
Create a workflow file in your repository -
.github/workflows/atlan-dbt.yml
. -
Add the following code to your workflow file:
name: Atlan action
on:
pull_request:
types: [opened, edited, synchronize, reopened, closed]
jobs:
get-downstream-impact:
name: Get Downstream Assets
runs-on: ubuntu-latest
steps:
- name: Run Action
uses: atlanhq/atlan-action@v1
with:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
ATLAN_INSTANCE_URL: ${{secrets.ATLAN_INSTANCE_URL}}
ATLAN_API_TOKEN: ${{secrets.ATLAN_API_TOKEN}}
-
Test the action
After you've completed the configuration described earlier, create a pull request with a changed dbt model file to test the action. You can expect to see the Atlan GitHub action running and then adding comments in your pull request:
- The GitHub workflow adds and update a single comment for every file change.
- The impacted assets in the comment are displayed in a collapsible section and grouped by source and asset type.
- The comment includes some metadata for your impacted assets - such as descriptions, owners, and linked glossary terms.
- View the impacted assets in Atlan or open the source URL - for example, view an impacted Looker dashboard directly in Looker.
- Once you have merged the pull request, it's added as a resource to the dbt model and its materialized assets. You can view the linked pull request from the Resources tab of the asset sidebar.
For example:
Inputs
Name | Description | Required |
---|---|---|
GITHUB_TOKEN | For writing comments on PRs to print downstream assets | true |
ATLAN_INSTANCE_URL | For making API requests to the user's tenant | true |
ATLAN_API_TOKEN | For authenticating API requests to the user's tenant | true |
DBT_ENVIRONMENT_BRANCH_MAP | For mapping the GitHub branch with a specific dbt environment | false |
IGNORE_MODEL_ALIAS_MATCHING | For turning off matching alternative names using this variable | false |
Troubleshooting the action
Why does the action fetch a model from an incorrect environment?
If there are multiple dbt models with the same name but across different environments in your Atlan instance, the action may fetch an incorrect model. In order to make sure that the action fetches a model from the right environment, you can map the GitHub branch with a specific dbt environment. This enables the Atlan GitHub action to parse lineage for that specific environment.
For example, you can provide the mapping in this format - branch name
: dbt environment name
jobs:
get-downstream-impact:
name: Get Downstream Assets
runs-on: ubuntu-latest
steps:
- name: Run Action
uses: atlanhq/atlan-action@v1
with:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
ATLAN_INSTANCE_URL: ${{secrets.ATLAN_INSTANCE_URL}}
ATLAN_API_TOKEN: ${{secrets.ATLAN_API_TOKEN}}
+ DBT_ENVIRONMENT_BRANCH_MAP: |
+ main: dbt-prod
+ beta: dbt-test
Why does the action fetch a model by its alternative name and not model name?
By default, the action checks if there is an alternative name defined for a dbt model in the code and looks for the relevant asset in Atlan using that alternative name. To turn off matching alternative names for your dbt models, you can set the IGNORE_MODEL_ALIAS_MATCHING
input to true.
For example:
jobs:
get-downstream-impact:
name: Get Downstream Assets
runs-on: ubuntu-latest
steps:
- name: Run Action
uses: atlanhq/atlan-action@v1
with:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
ATLAN_INSTANCE_URL: ${{secrets.ATLAN_INSTANCE_URL}}
ATLAN_API_TOKEN: ${{secrets.ATLAN_API_TOKEN}}
+ IGNORE_MODEL_ALIAS_MATCHING: true