Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs Update #102

Merged
merged 4 commits into from
May 15, 2023
Merged

Docs Update #102

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c421226
Merge remote-tracking branch 'origin/main' into docs
cmgrote Jan 19, 2023
ce2406b
Merge branch 'staging' into docs
Jaagrav May 15, 2023
ebff6cf
fix: docs update for new features
Jaagrav May 15, 2023
aa99ff7
fix: requested docs changes
Jaagrav May 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 84 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## Overview

*Have you ever changed a dbt model only to later find it broke a downstream table or dashboard? 💔*
_Have you ever changed a dbt model only to later find it broke a downstream table or dashboard? 💔_

We've created a GitHub Action to help you out — putting Atlan's impact analysis right into your pull request. So now, before merging the PR, you can see the potential downstream impact of your changes.

Expand All @@ -19,44 +19,95 @@ Here's what it looks like 👇
## Configure the action

1. Create [repository secrets](https://github.com/Azure/actions-workflow-samples/blob/master/assets/create-secrets-for-GitHub-workflows.md#creating-secrets) in your repository:
- `ATLAN_INSTANCE_URL` with the URL of your Atlan instance.
- `ATLAN_API_TOKEN` with the value of the API token.

![Actions Secrets Screenshot](https://iili.io/HI7gfx2.png)
- `ATLAN_INSTANCE_URL` with the URL of your Atlan instance.
- `ATLAN_API_TOKEN` with the value of the API token.

![Actions Secrets Screenshot](https://iili.io/HI7gfx2.png)

2. Add the GitHub Action to your workflow:
1. Create a workflow file in your repository: `.github/workflows/atlan-dbt.yml`
2. Add the following code to the workflow file:

```yaml
name: Atlan dbt 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/dbt-action@v1
with:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
ATLAN_INSTANCE_URL: ${{secrets.ATLAN_INSTANCE_URL}}
ATLAN_API_TOKEN: ${{secrets.ATLAN_API_TOKEN}}
```

1. Create a workflow file in your repository: `.github/workflows/atlan-dbt.yml`
2. Add the following code to the workflow file:

```yaml
name: Atlan dbt 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/dbt-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
To test the action, after you've completed the configuration above create a pull request with a changed dbt model file. You should see the Atlan
GitHub action running and then adding comments in your pull request.
After you've completed the configuration above, create a pull request with a changed dbt model file to test the action. You should see the Atlan GitHub action running and then adding comments in your pull request:
- The GitHub workflow will add and update a single comment for every file change.
- The impacted assets in the comment will be displayed in a collapsible section and grouped by source and asset type.
- The comment will include 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.
## Inputs
| Name | Description | Required |
|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `GITHUB_TOKEN` | Needed to write comments on PRs to print all the downstream assets. https://dev.to/github/the-githubtoken-in-github-actions-how-it-works-change-permissions-customizations-3cgp | true |
| `ATLAN_INSTANCE_URL` | Needed for making API requests to the user's tenant. | true |
| `ATLAN_API_TOKEN` | Needed for authenticating API requests to the user's tenant. https://ask.atlan.com/hc/en-us/articles/8312649180049 | true |
| Name | Description | Required | Default |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| `GITHUB_TOKEN` | Needed to write comments on PRs to print all the downstream assets. https://dev.to/github/the-githubtoken-in-github-actions-how-it-works-change-permissions-customizations-3cgp | true |
| `ATLAN_INSTANCE_URL` | Needed for making API requests to the user's tenant. | true |
| `ATLAN_API_TOKEN` | Needed for authenticating API requests to the user's tenant. https://ask.atlan.com/hc/en-us/articles/8312649180049 | true |
| `DBT_ENVIRONMENT_BRANCH_MAP` | Map Github branch with specific dbt environment, if you do this - Atlan Github action will pick lineage for that specific environment from Atlan.You can provide the mapping like `branch name`: `dbt environment name`. <br><br>main: DBT-DEMO-PROD<br>beta: Wide World Importers PE1<br>test-action: Wide World Importers PE1 | false |
| `IGNORE_MODEL_ALIAS_MATCHING` | By default the action checks if there's an alias defined for a model in the code and looks for the relevant asset in Atlan using that alias. You can turn off matching alias name using this variable. | false | false |

## FAQs

### Action does not get the model from the correct environment?

In case there are multiple dbt models in your Atlan instance with the same name but in different environments, the action may get the wrong model. To fix this, you can map Github branch with specific dbt environment, if you do this - Atlan Github action will pick lineage for that specific environment from Atlan.
You can provide the mapping like `branch name`: `dbt nvironment name`

```diff
jobs:
get-downstream-impact:
name: Get Downstream Assets
runs-on: ubuntu-latest
steps:
- name: Run Action
uses: atlanhq/dbt-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
```

### Action gets model by alias and not by model name?

By default the action checks if there's an alias defined for a model in the code and looks for the relevant asset in Atlan using that alias. You can turn off matching alias name using this input `IGNORE_MODEL_ALIAS_MATCHING` input to true. For example:

```diff
jobs:
get-downstream-impact:
name: Get Downstream Assets
runs-on: ubuntu-latest
steps:
- name: Run Action
uses: atlanhq/dbt-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
```