Skip to main content

How to open pull requests with Foundational IQ

Introduction

Foundational’s IQ chatbot can open a pull request (PR) for you. Ask Foundational IQ to make a code change, review the proposed patch, and approve. Foundational IQ uses your credentials to push the branch and open the PR on your git host without you leaving Foundational.

PRs are authored under your own identity, not a shared bot account. Your name is on it on GitHub, GitLab, Bitbucket, or Azure DevOps Repos.

What you need

A Personal Access Token (PAT) registered in your account settings.

This is a one-time setup. Foundational IQ uses that token to push a branch and open the PR on your behalf.

How it works

Here’s the Foundational IQ workflow that needs your approval before activation.

① Ask Foundational IQ: Describe the change you want in plain language.
​

② Foundational IQ proposes a patch: IQ analyzes your codebase and returns a diff card in chat. Foundational IQ does not push anything yet.
​

③ Approve in Foundational IQ: Ask it to open the PR or click Open PR on the diff card. IQ presents a confirmation card and waits. The gate is hard-wired: Foundational IQ cannot open a PR without you clicking through.
​

④ IQ pushes the branch: On approval, Foundational IQ selects credentials based on your platform and pushes a branch to the repo's default branch.

Platform

Credentials used

GitLab, Bitbucket, Azure Repos

Your linked PAT

Org-level credentials configured during platform connection

⑤ Pull request opens on your git host: Foundational IQ opens the PR as a draft and returns a result card in chat with a clickable link. To open a ready-for-review PR instead, ask Foundational IQ explicitly when making your request.

Foundational IQ UI

Foundational IQ opens pull requests on your behalf using these tokens, so PRs are authored by your user on each platform. Only platforms your organization has connected appear here.

Each platform row shows one of two states:

  • Unlinked: Setup instructions, input fields, and a Link token button.
    ​

  • Linked: A summary card showing Linked as (username), Scopes (or "Fine-grained token (per-repo permissions)" if the platform returns no scopes), Instance (for self-managed platforms), Org (for Azure Repos), Linked on, Expires, and a Remove token button.

For detailed registration steps, see Actions.

Actions

Register a personal access token for GitHub

You only register your PAT once. To remove a linked token at any time, return to Personal access tokens and click Remove token next to the platform.

  1. In GitHub, go to Settings → Personal access tokens → Fine-grained tokens and create a new token with these settings:
    ​

    • Resource owner: Your organization (not your personal account)
      ​

    • Repository access: Only select repositories. Select the repos Foundational IQ should open PRs for
      ​

    • Contents: Read & write
      ​

    • Pull requests: Read & write
      ​

  2. If your organization enforces SAML SSO, click Configure SSO next to the token and authorize it for your organization.
    ​

  3. Copy the token.
    ​

  4. In Foundational, click your avatar, then Account Settings.
    ​

  5. In the left pane, click Personal access tokens.
    ​

  6. Locate the GitHub row and click Link token.
    ​

  7. Personal Access Token: Paste the token and click Link token.

Foundational validates the token immediately. If the token is missing required scopes or has already expired, an inline error appears and the token is not saved.

Classic personal access tokens with the repo scope also work. If your organization requires admin approval for fine-grained tokens, paste the token while it is pending; Foundational IQ starts using it when it is approved.

Foundational sends your token to the platform for validation and stores it encrypted. Foundational never sees the raw token.

Register a personal access token for GitLab

  1. In GitLab, go to User settings → Access tokens and create a new token with these settings:
    ​

    • Name: Set a name
      ​

    • Expiration date: Set an expiration date
      ​

    • Scope: api (or more narrowly, write_repository + read_api)
      ​

    • Role: Developer or above on the relevant projects or groups
      ​

  2. If your group uses SAML SSO, sign in to the group via SSO before generating the token and refresh the SSO session periodically.
    ​

  3. Click Create personal access token and copy the value. GitLab will not show it again.
    ​

  4. In Foundational, click your avatar, then Account Settings.
    ​

  5. In the left pane, click Personal access tokens.
    ​

  6. Locate the GitLab row and click Link token.
    ​

  7. Instance URL: If you use self-managed GitLab, enter your instance URL (for example). Leave it blank for gitlab.com.
    ​

  8. Personal Access Token: Paste the token. The placeholder shows glpat-....
    ​

  9. Click Link token.

Foundational validates the token immediately. If the token is missing required scopes or has already expired, an inline error appears and the token is not saved.

Foundational sends your token to the platform for validation and stores it encrypted. Foundational never logs the raw token.

Register a personal access token for Bitbucket

Bitbucket supports three token types:

  • Atlassian API token: Recommended for Bitbucket Cloud
    ​

  • HTTP access token: For Bitbucket Server or Data Center

Bitbucket Cloud: Atlassian API token (recommended)

  1. Go to id.atlassian.com, then Security, then API tokens and create a new token with these settings:
    ​

    • App: Bitbucket
      ​

    • Token name: Set a name
      ​

    • Expiration: Set an expiration date
      ​

    • Scopes: read:repository:bitbucket + write:repository:bitbucket, read:pullrequest:bitbucket + write:pullrequest:bitbucket

  2. Copy the token.
    ​

  3. In Foundational, click your avatar, then Account Settings.
    ​

  4. In the left pane, click Personal access tokens.
    ​

  5. Locate the Bitbucket row and click Link token.
    ​

  6. Username: Enter the Atlassian account email the token was created under.
    ​

  7. Personal Access Token: Paste the token and click Link token.

Bitbucket Cloud: Legacy App Password

  1. Go to Bitbucket, then Personal settings, then App passwords and create a new app password with these settings:
    ​

    • Repositories: Write
      ​

    • Pull requests: Write
      ​

  2. Copy the app password.
    ​

  3. In Foundational, click your avatar, then Account Settings.
    ​

  4. In the left pane, click Personal access tokens.
    ​

  5. Locate the Bitbucket row and click Link token.
    ​

  6. Username: Enter your Bitbucket username slug (find it at bitbucket.org/account/settings, the value labeled "Username", not your display name).
    ​

  7. Personal Access Token: Paste the app password and click Link token.

Bitbucket Server / Data Center

  1. In your Bitbucket Server, go to Profile, then Manage account, then HTTP access tokens and create a new token with these settings:
    ​

    • Project: Write
      ​

    • Repository: Write
      ​

  2. Copy the token.
    ​

  3. In Foundational, click your avatar, then Account Settings.
    ​

  4. In the left pane, click Personal access tokens.
    ​

  5. Locate the Bitbucket row and click Link token.
    ​

  6. Instance URL: Enter your server instance URL. Username: Enter your username slug.
    ​

  7. Personal Access Token: Paste the token and click Link token.

Foundational validates the token immediately. If the token is missing required scopes or has already expired, an inline error appears and the token is not saved.

Foundational sends your token to the platform for validation and stores it encrypted. Foundational never logs the raw token.

Register a personal access token for Azure DevOps

Azure DevOps PATs are scoped to a single organization. Only one Azure DevOps organization per user is supported. Linking a second organization overwrites the first.

  1. Sign in to Azure DevOps and switch to the organization you want to link.
    ​

  2. Go to User settings (top right), then Personal access tokens (direct URL: https://dev.azure.com/{org}/_usersSettings/tokens) and create a new token with these settings:
    ​

    • Token name: Set a name
      ​

    • Expiration: Set an expiration date
      ​

    • Scopes: Custom defined
      ​

    • Code: Read & write
      ​

    • Status: Checked. Required for Foundational IQ to post PR status checks
      ​

  3. Copy the token.
    ​

  4. In Foundational, click your avatar, then Account Settings.
    ​

  5. In the left pane, click Personal access tokens.
    ​

  6. Locate the Azure DevOps row and click Link token.
    ​

  7. Organization: Enter your Azure DevOps organization name.
    ​

  8. Personal Access Token: Paste the token and click Link token.

Foundational validates the token immediately. If the token is missing required scopes or has already expired, an inline error appears and the token is not saved.

Foundational sends your token to the platform for validation and stores it encrypted. Foundational never logs the raw token.

Open a pull request with Foundational IQ


Before Foundational IQ opens the PR, it runs eligibility checks:

  • PR creation must be enabled for your organization
    ​

  • The proposal must include file changes

Steps:

  1. From the menu pane, open Foundational IQ.
    ​

  2. Describe the code change you want in plain language. For example: "Add a not_null test to the users.email column."
    ​

  3. Foundational IQ analyzes your codebase and proposes a patch. Review the diff card in chat.
    ​

  4. To open a PR, either:
    ​

    • Click Open PR on the diff card, or
      ​

    • Send a follow-up message such as "open the PR" or "yes, open it."
      ​

  5. On the confirmation card, click one of:
    ​

    • Open PR to confirm. The button changes to Approved.
      ​

    • Cancel to discard. The button changes to Cancelled.
      ​

    • Download Patch to save the patch file locally, if available.

Foundational IQ pushes a branch to the repo's default branch and opens the PR as a draft. The result card in chat shows a green checkmark and a clickable link to the PR on your git host.

PRs are always drafts unless you ask for a ready-for-review PR. To open a non-draft PR, include "open it ready for review" in your request. PRs are authored by your user identity, not by a Foundational bot.

Troubleshooting

If Foundational IQ cannot open the PR, it renders a yellow Action required card in chat. The table shows each error and how to resolve it.

Error

Message

Resolution

No GitHub PAT linked

Link a GitHub PAT to let IQ open this PR.

Click Link GitHub PAT to go to Account Settings and add your token.

PAT expired or revoked

Your linked GitHub PAT has expired or was revoked. Re-link it in your settings.

Click Update GitHub PAT and replace the token.

SAML SSO not authorized

Your GitHub PAT needs SSO authorization for this organization. Authorize the PAT on GitHub and try again.

Click Authorize SSO to go to the GitHub SSO authorization page.

PAT lacks repo access

Your linked PAT does not have access to {repo_name}. Verify the PAT scopes and SSO authorization.

Click Review PAT scopes to go to your GitHub tokens page and update permissions.

Unexpected error

GitHub returned an unexpected error (status {N}).

Click Open settings to go to Account Settings and re-link your token.

Related Articles
Continuously Check Your Pull Requests with Foundational CI
How to set up Azure Repos
How to set up Bitbucket
How to set up Talend ETL
What can Foundational IQ do for you?
Did this answer your question?