Skip to main content

Connecting GitHub to DataHub Cloud: Common Errors and How to Resolve Them

Angelo Bresci
Updated

Area: Deployment Issues

Sub-Area: GitHub Integration / OAuth Authorization Flow

Issue

When setting up the GitHub integration in DataHub Cloud, users may encounter one or more errors during the OAuth authorization flow. Two errors are especially common: a missing security state token (triggered when the installation is initiated from the GitHub side rather than from within DataHub) and a GitHub organization owner permission error (triggered when the user completing the final authorization step is not an owner of the GitHub organization). Both errors block the integration from completing even when the DataHub GitHub App is already installed in the GitHub organization.

Error Messages

  • loc: ["query", "state"] msg: "Field required"
  • This action must be performed by an organization owner

You Might Be Asking

  • Why do I get a "Field required" / missing state error after installing the DataHub GitHub App and being redirected back to DataHub?
  • Why does GitHub say I need to be an organization owner even though I already have admin access in DataHub?
  • Can I install the GitHub App from the GitHub Marketplace or GitHub organization settings, or does it have to be done from inside DataHub?
  • Do I need to reinstall the GitHub App to fix these errors, or is the existing installation reusable?

Solution

Work through the two errors in order. The existing GitHub App installation does not need to be removed or reinstalled at any stage.

  1. Always start the connection from inside DataHub, not from GitHub.

    The state token that protects the OAuth callback is generated only when the flow is initiated from within DataHub. If you navigate to the GitHub App installation page directly (for example, from the GitHub Marketplace or from your GitHub organization's settings) and are then redirected back to DataHub, the token will be absent and the connection will fail with the "Field required" error.

    To start the flow correctly:

    1. Sign in to your DataHub Cloud instance at https://<your-instance>.acryl.io.
    2. Navigate to Settings > Integrations > GitHub.
    3. Click Connect (or Install GitHub App if the app has not yet been linked). This generates the required state token before handing off to GitHub.

    If the DataHub GitHub App was already installed in your GitHub organization by another user, GitHub will recognize the existing installation during this flow and reuse it — no reinstallation is required.

  2. Ensure a GitHub organization owner completes the entire authorization flow end-to-end.

    The final GitHub authorization screen — which may be labelled "Update access" or ask you to approve repository permissions — can only be approved by a user who is an owner of the GitHub organization. Admin access inside DataHub is unrelated to GitHub organization ownership. A user who is a repository admin (but not an organization owner) can install the GitHub App on selected repositories, but cannot approve the organization-level authorization that DataHub requires.

    Steps for the organization owner:

    1. Open a browser session where you are signed in to GitHub as an organization owner of the target GitHub organization.
    2. In the same browser session, navigate to your DataHub Cloud instance: https://<your-instance>.acryl.io.
    3. Go to Settings > Integrations > GitHub and click Connect / Install GitHub App.
    4. Complete the GitHub authorization screen that appears. The entire flow — from clicking Connect in DataHub to approving the GitHub screen — must be completed by the same person in the same browser session. The OAuth state token expires after approximately 10 minutes, so do not pause between steps.
    5. After approval, GitHub will redirect back to DataHub and the integration will show as configured.
  3. Verify that the correct repositories are selected in the GitHub App settings.

    After the connection is established, confirm that all intended repositories are granted to the DataHub GitHub App:

    1. In GitHub, go to your organization's Settings > Third-party Access > GitHub Apps.
    2. Find the DataHub Cloud App and click Configure.
    3. Under Repository access, verify that all required repositories are listed. If the screen shows "No repositories selected," add them explicitly or choose "All repositories" as appropriate for your organization's policy.
  4. Configure a GitHub documents source for your repositories.

    Once the integration shows as connected in DataHub, set up a GitHub documents ingestion source to bring your repositories' content into DataHub as metadata context:

    # Example DataHub ingestion recipe for GitHub documents
source:
  type: github
  config:
    # GitHub organization name
    github_org: <your-github-org>
    # List of repositories to ingest
    repos:
      - <repo-name-1>
      - <repo-name-2>
      - <repo-name-3>

sink:
  type: datahub-rest
  config:
    server: "https://<your-instance>.acryl.io/api/gms"

    Alternatively, configure the GitHub documents source through the DataHub Cloud UI under Ingestion > Create new source > GitHub.

Additional Notes

  • The missing state token error ("Field required") is a known issue in certain DataHub Cloud versions. The workaround — always initiating the connection from within DataHub — is fully effective. A fix was targeted for the next release at the time this article was written.
  • GitHub distinguishes between organization owners and repository admins. Installing the app on specific repositories requires only repository admin rights, but linking the app to DataHub at the organization level requires an organization owner. These two steps may therefore need to be performed by different people in your organization.
  • The OAuth state token is time-limited (approximately 10 minutes). The organization owner must complete the full flow — from DataHub's Connect button through GitHub's approval screen — without interruption in a single browser session.
  • Admin access inside DataHub does not confer any GitHub organization permissions and is not a substitute for GitHub organization ownership.
  • If your browser blocks pop-ups, ensure pop-ups are permitted for your DataHub Cloud domain before initiating the OAuth flow.

Related Documentation

Tags: github-integration, oauth, github-app, datahub-cloud, organization-owner, state-token, authorization, ingestion, onboarding, integration-setup