terraform private module registry terraform cloud docs registry policy sets terraform cloud docs policy enforcement manage policy sets tfc only true page title GitHub com GitHub App VCS Providers HCP Terraform Learn how to use GitHub com repositories with workspaces and private registry modules without requiring an organization owner to configure an OAuth connection

Answer:
---
page_title: GitHub.com (GitHub App) - VCS Providers - HCP Terraform
tfc_only: true
description: >-
  Learn how to use GitHub.com repositories with workspaces and private registry modules, without requiring an organization owner to configure an OAuth connection.
---

[private module registry]: /terraform/cloud-docs/registry

[policy sets]: /terraform/cloud-docs/policy-enforcement/manage-policy-sets

[vcs settings]: /terraform/cloud-docs/workspaces/settings/vcs

[create]: /terraform/cloud-docs/workspaces/create

[owners]: /terraform/cloud-docs/users-teams-organizations/teams#the-owners-team

# Configuration-Free GitHub Usage

These instructions are for using repositories from GitHub.com with HCP Terraform workspaces and private registry modules, without requiring an organization owner to configure an OAuth connection.

This method uses a preconfigured GitHub App, and only works with GitHub.com. There are separate instructions for connecting to [GitHub.com via OAuth](/terraform/cloud-docs/vcs/github), connecting to [GitHub Enterprise](/terraform/cloud-docs/vcs/github-enterprise), and connecting to [other supported VCS providers.](/terraform/cloud-docs/vcs)

-> **Note:** This VCS Provider is only available on HCP Terraform. If you are using Terraform Enterprise, you can follow the instructions for creating [GitHub App for TFE](/terraform/enterprise/admin/application/github-app-integration) or connecting to [GitHub.com via OAuth](/terraform/cloud-docs/vcs/github).

## Using GitHub Repositories

Choose "GitHub.com" on the "Connect to a version control provider" screen, which is shown when [creating a new workspace][create] or [changing a workspace's VCS connection][vcs settings]. Authorize access to GitHub if necessary. On the next screen, select a GitHub account or organization from the drop-down menu (or add a new organization) and choose a repository from the list.

The controls on the "Connect to a version control provider" screen can vary, depending on your permissions and your organization's settings:

- In organizations with no VCS connections configured:
  - Users with permission to manage VCS settings ([more about permissions](/terraform/cloud-docs/users-teams-organizations/permissions)) will see several drop-down menus, sorted by product family. Choose "GitHub.com" (_not_ "GitHub.com (Custom)") from the GitHub menu.
  - Other users will see a "GitHub" button.
- In organizations with an existing VCS connection, only the connected providers are shown. Click the "Connect to a different VCS" link to reveal the provider menus (if you can manage VCS settings) or the GitHub button (others).

[permissions-citation]: #intentionally-unused---keep-for-maintainers

## GitHub Permissions

When using the Terraform Cloud GitHub App, each HCP Terraform user authenticates individually, and can use GitHub resources within HCP Terraform according to their own GitHub organization memberships and access permissions.

-> **Note:** This is different from OAuth connections, where an HCP Terraform organization always acts as one particular GitHub user.

To enable this personalized access, HCP Terraform requests two kinds of permissions:

- **Per user:** Each HCP Terraform user must _authorize_ HCP Terraform for their own GitHub account. This lets HCP Terraform determine which organizations and repositories they have access to.
- **Per GitHub organization:** Each GitHub organization (or personal account) must _install_ the Terraform Cloud app, either globally or for specific repositories. This allows HCP Terraform to access repository contents and events.

Individual HCP Terraform users can access GitHub repositories where both of the following are true:

- The user has at least read access to that repository on GitHub.
- The repository's owner has installed the Terraform Cloud app and allowed it to access that repository.

This means that different HCP Terraform users within the same organization can see different sets of repositories available for their workspaces.

### Authorizing

HCP Terraform requests GitHub authorization from each user, displaying a pop-up window the first time they choose GitHub on the "Connect to a version control provider" screen.

![Screenshot: GitHub asking whether you want to authorize "Terraform Cloud by HashiCorp".](/img/docs/gh-app-authorize.png)

Once you authorize the app, you can use GitHub in any of your HCP Terraform organizations without needing to re-authorize.

After installing the GitHub App and creating your VCS provider instance, you cannot reinstall the application again. However, you can modify your existing GitHub App configuration.

If you are a repository owner, you can adjust an existing Github App configuration by:
1. Click a repository's **Settings** tab.
1. Select **GitHub Apps** in the sidebar.
1. Next to **Terraform Cloud**, click **Configure**.
1. Underneath **Repository access**, adjust the repositories your GitHub app can access.

Now that your Github app has access to your desired repository, you can [create a new workspace](/terraform/cloud-docs/workspaces/create#create-a-workspace) with your existing, newly updated GitHub App connection.

You can also adjust your GitHub App's access within HCP Terraform itself.  Whenever you create a new workspace, you can choose which organizations or repositories to install the GitHub App into. To adjust your GitHub App's configuration, create a new workspace:
1. Click **Workspaces** in the sidebar.
1. Click **New**, then select **Workspace**.
1. Choose the project where you want to create your workspace, then click **Create**.
1. Click **Version Control Workflow**, then choose the **GitHub App**.
1. Click on your GitHub organization's name to reveal a dropdown, then select **Add another organization** to configure the resources your GitHub app has access to.

#### Deauthorizing

You can use GitHub's web interface to deauthorize HCP Terraform for your GitHub account.

Open your GitHub personal settings, then go to the "Applications" section and the "Authorized GitHub Apps" tab. (Or, browse directly to `https://github.com/settings/apps/authorizations`.) Click the **Revoke** button for HCP Terraform to deauthorize it.

After deauthorizing, you won't be able to connect GitHub repositories to HCP Terraform workspaces until you authorize again. Existing connections will still work.

### Installing

HCP Terraform requests installation when a user chooses "Add another organization" from the repository list's organization menu.

The installation interface is a pop-up GitHub window, which lists your personal account and the organizations you can access. Note that installing an app for a GitHub organization requires appropriate organization permissions; see [GitHub's permissions documentation](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization#github-app-managers) for details.

![Screenshot: GitHub asking which organization or account to install the Terraform Cloud app in](/img/docs/gh-app-install-pick.png)

For a given organization or account, the app can be installed globally or only for specific repositories.

Once the application is installed for an organization (or a subset of its repositories), its members can select any affected repositories they have access to when using HCP Terraform.

Access is not restricted to a specific HCP Terraform organization; members of a GitHub organization can use its repositories in any HCP Terraform organization they belong to.

#### Configuring and Uninstalling

You can use GitHub's web interface to configure or uninstall HCP Terraform for an organization or account.

Open your GitHub personal settings or organization settings, then go to the **Applications** section and the *Installed GitHub Apps** tab. Click the **Configure** button for HCP Terraform to change its settings.

In the app's settings you can change which repositories HCP Terraform has access to, or uninstall it entirely.

If you disallow access to a repository that is currently connected to any HCP Terraform workspaces, those workspaces will be unable to retrieve configuration versions until you change their VCS settings and connect them to an allowed repository.

## Feature Limitations

You can use the Terraform Cloud GitHub App to create workspaces and private registry modules from the UI, the API, or the TFE Terraform provider.  The following tools can use any version of HCP Terraform to access these features, but require a minimum version of Terraform Enterprise:

- For the UI, use Terraform Enterprise v202302-1 or above.
- For the API, use Terraform Enterprise v202303-1 or above.
- Using at least v1.19.0 of [`go_tfe`](https://github.com/hashicorp/go-tfe), use Terraform Enterprise v202303-1 and above.
- Using at least v0.43.0 of [`tfe_provider`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs), use Terraform Enterprise v202303-1 and above.

Once you decide to start using these other features, a user with permission to manage VCS settings can configure [GitHub OAuth access](/terraform/cloud-docs/vcs/github) for your organization. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

page title  GitHub com  GitHub App    VCS Providers   HCP Terraform tfc only  true description       Learn how to use GitHub com repositories with workspaces and private registry modules  without requiring an organization owner to configure an OAuth connection        private module registry    terraform cloud docs registry   policy sets    terraform cloud docs policy enforcement manage policy sets   vcs settings    terraform cloud docs workspaces settings vcs   create    terraform cloud docs workspaces create   owners    terraform cloud docs users teams organizations teams the owners team    Configuration Free GitHub Usage  These instructions are for using repositories from GitHub com with HCP Terraform workspaces and private registry modules  without requiring an organization owner to configure an OAuth connection   This method uses a preconfigured GitHub App  and only works with GitHub com  There are separate instructions for connecting to  GitHub com via OAuth   terraform cloud docs vcs github   connecting to  GitHub Enterprise   terraform cloud docs vcs github enterprise   and connecting to  other supported VCS providers    terraform cloud docs vcs        Note    This VCS Provider is only available on HCP Terraform  If you are using Terraform Enterprise  you can follow the instructions for creating  GitHub App for TFE   terraform enterprise admin application github app integration  or connecting to  GitHub com via OAuth   terraform cloud docs vcs github       Using GitHub Repositories  Choose  GitHub com  on the  Connect to a version control provider  screen  which is shown when  creating a new workspace  create  or  changing a workspace s VCS connection  vcs settings   Authorize access to GitHub if necessary  On the next screen  select a GitHub account or organization from the drop down menu  or add a new organization  and choose a repository from the list   The controls on the  Connect to a version control provider  screen can vary  depending on your permissions and your organization s settings     In organizations with no VCS connections configured      Users with permission to manage VCS settings   more about permissions   terraform cloud docs users teams organizations permissions   will see several drop down menus  sorted by product family  Choose  GitHub com    not   GitHub com  Custom    from the GitHub menu      Other users will see a  GitHub  button    In organizations with an existing VCS connection  only the connected providers are shown  Click the  Connect to a different VCS  link to reveal the provider menus  if you can manage VCS settings  or the GitHub button  others     permissions citation    intentionally unused   keep for maintainers     GitHub Permissions  When using the Terraform Cloud GitHub App  each HCP Terraform user authenticates individually  and can use GitHub resources within HCP Terraform according to their own GitHub organization memberships and access permissions        Note    This is different from OAuth connections  where an HCP Terraform organization always acts as one particular GitHub user   To enable this personalized access  HCP Terraform requests two kinds of permissions       Per user    Each HCP Terraform user must  authorize  HCP Terraform for their own GitHub account  This lets HCP Terraform determine which organizations and repositories they have access to      Per GitHub organization    Each GitHub organization  or personal account  must  install  the Terraform Cloud app  either globally or for specific repositories  This allows HCP Terraform to access repository contents and events   Individual HCP Terraform users can access GitHub repositories where both of the following are true     The user has at least read access to that repository on GitHub    The repository s owner has installed the Terraform Cloud app and allowed it to access that repository   This means that different HCP Terraform users within the same organization can see different sets of repositories available for their workspaces       Authorizing  HCP Terraform requests GitHub authorization from each user  displaying a pop up window the first time they choose GitHub on the  Connect to a version control provider  screen     Screenshot  GitHub asking whether you want to authorize  Terraform Cloud by HashiCorp     img docs gh app authorize png   Once you authorize the app  you can use GitHub in any of your HCP Terraform organizations without needing to re authorize   After installing the GitHub App and creating your VCS provider instance  you cannot reinstall the application again  However  you can modify your existing GitHub App configuration   If you are a repository owner  you can adjust an existing Github App configuration by  1  Click a repository s   Settings   tab  1  Select   GitHub Apps   in the sidebar  1  Next to   Terraform Cloud    click   Configure     1  Underneath   Repository access    adjust the repositories your GitHub app can access   Now that your Github app has access to your desired repository  you can  create a new workspace   terraform cloud docs workspaces create create a workspace  with your existing  newly updated GitHub App connection   You can also adjust your GitHub App s access within HCP Terraform itself   Whenever you create a new workspace  you can choose which organizations or repositories to install the GitHub App into  To adjust your GitHub App s configuration  create a new workspace  1  Click   Workspaces   in the sidebar   1  Click   New    then select   Workspace    1  Choose the project where you want to create your workspace  then click   Create    1  Click   Version Control Workflow    then choose the   GitHub App    1  Click on your GitHub organization s name to reveal a dropdown  then select   Add another organization   to configure the resources your GitHub app has access to         Deauthorizing  You can use GitHub s web interface to deauthorize HCP Terraform for your GitHub account   Open your GitHub personal settings  then go to the  Applications  section and the  Authorized GitHub Apps  tab   Or  browse directly to  https   github com settings apps authorizations    Click the   Revoke   button for HCP Terraform to deauthorize it   After deauthorizing  you won t be able to connect GitHub repositories to HCP Terraform workspaces until you authorize again  Existing connections will still work       Installing  HCP Terraform requests installation when a user chooses  Add another organization  from the repository list s organization menu   The installation interface is a pop up GitHub window  which lists your personal account and the organizations you can access  Note that installing an app for a GitHub organization requires appropriate organization permissions  see  GitHub s permissions documentation  https   help github com en github setting up and managing organizations and teams permission levels for an organization github app managers  for details     Screenshot  GitHub asking which organization or account to install the Terraform Cloud app in   img docs gh app install pick png   For a given organization or account  the app can be installed globally or only for specific repositories   Once the application is installed for an organization  or a subset of its repositories   its members can select any affected repositories they have access to when using HCP Terraform   Access is not restricted to a specific HCP Terraform organization  members of a GitHub organization can use its repositories in any HCP Terraform organization they belong to        Configuring and Uninstalling  You can use GitHub s web interface to configure or uninstall HCP Terraform for an organization or account   Open your GitHub personal settings or organization settings  then go to the   Applications   section and the  Installed GitHub Apps   tab  Click the   Configure   button for HCP Terraform to change its settings   In the app s settings you can change which repositories HCP Terraform has access to  or uninstall it entirely   If you disallow access to a repository that is currently connected to any HCP Terraform workspaces  those workspaces will be unable to retrieve configuration versions until you change their VCS settings and connect them to an allowed repository      Feature Limitations  You can use the Terraform Cloud GitHub App to create workspaces and private registry modules from the UI  the API  or the TFE Terraform provider   The following tools can use any version of HCP Terraform to access these features  but require a minimum version of Terraform Enterprise     For the UI  use Terraform Enterprise v202302 1 or above    For the API  use Terraform Enterprise v202303 1 or above    Using at least v1 19 0 of   go tfe   https   github com hashicorp go tfe   use Terraform Enterprise v202303 1 and above    Using at least v0 43 0 of   tfe provider   https   registry terraform io providers hashicorp tfe latest docs   use Terraform Enterprise v202303 1 and above   Once you decide to start using these other features  a user with permission to manage VCS settings can configure  GitHub OAuth access   terraform cloud docs vcs github  for your organization    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers


terraform page title GitLab com VCS Providers HCP Terraform These instructions are for using GitLab com for HCP Terraform s VCS features GitLab CE and GitLab EE have separate instructions terraform cloud docs vcs gitlab eece as do the other supported VCS providers terraform cloud docs vcs Learn how to use GitLab com for VCS features Configuring GitLab com Access

Answer:
---
page_title: GitLab.com - VCS Providers - HCP Terraform
description: >-
  Learn how to use GitLab.com for VCS features.
---

# Configuring GitLab.com Access

These instructions are for using GitLab.com for HCP Terraform's VCS features. [GitLab CE and GitLab EE have separate instructions,](/terraform/cloud-docs/vcs/gitlab-eece) as do the [other supported VCS providers.](/terraform/cloud-docs/vcs)

Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Connecting HCP Terraform to your VCS involves four steps:

| On your VCS                                                                    | On HCP Terraform                                                          |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
|                                                                                | Create a new connection in HCP Terraform. Get redirect URI.               |
| Register your HCP Terraform organization as a new app. Provide redirect URI. |                                                                             |
|                                                                                | Provide HCP Terraform with application ID and secret. Request VCS access. |
| Approve access request.                                                        |                                                                             |

The rest of this page explains the GitLab.com versions of these steps.

-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/cloud-docs/api-docs/oauth-clients).

## Step 1: On HCP Terraform, Begin Adding a New VCS Provider

1. Go to your organization's settings and then click **Providers**. The **VCS Providers** page appears.

1. Click **Add VCS Provider**. The **VCS Providers** page appears.

1. Select **GitLab** and then select **GitLab.com** from the menu. The page moves to the next step.

1. Locate the "Redirect URI" and copy it to your clipboard; you'll paste it in the next step.

Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform.

## Step 2: On GitLab, Create a New Application

1. In a new browser tab, open [gitlab.com](https://gitlab.com) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work.

   ~> **Important:** The account you use for connecting HCP Terraform **must have Maintainer access** to any shared repositories of Terraform configurations, since creating webhooks requires Maintainer permissions. Refer to [the GitLab documentation](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions) for details.

1. Navigate to GitLab's [User Settings > Applications](https://gitlab.com/-/profile/applications) page.

   This page is located at <https://gitlab.com/-/profile/applications>. You can also reach it through GitLab's menus:

   - Click your profile picture and choose "Settings."
   - Click "Applications."

1. This page has a list of applications and a form for adding new ones. The form has two text fields and some checkboxes.

   Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard.

   Fill out the form as follows:

   | Field                   | Value                                                                                |
   | ----------------------- | ------------------------------------------------------------------------------------------------ |
   | Name                    | HCP Terraform (`<YOUR ORGANIZATION NAME>`)                                                     |
   | Redirect URI            | `https://app.terraform.io/<YOUR CALLBACK URL>`, the redirect URI you copied from HCP Terraform |
   | Confidential (checkbox) | ✔ (enabled)                                                                                |
   | Scopes (all checkboxes) | api                                                                                |

1. Click the "Save application" button, which creates the application and takes you to its page.

1. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Application ID** and **Secret.**

## Step 3: On HCP Terraform, Set up Your Provider

1. Enter the **Application ID** and **Secret** from the previous step, as well as an option **Name** for this VCS connection.

1. Click **Connect and continue.** This takes you to a page on GitLab.com, which asks if you want to authorize the app.

1. Click the green **Authorize** button at the bottom of the authorization page.

## Step 4: On HCP Terraform, Configure Advanced Settings (Optional)

The settings in this section are optional. The Advanced Settings you can configure are:
- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization.
- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time.

### If You Don't Need to Configure Advanced Settings:

1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new GitLab client.

### If You Need to Limit the Scope of this VCS Provider:

1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider.

1. Click the **Update VCS Provider** button to save your selections.

### If You Do Need an SSH Keypair:

#### Important Notes

- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS.
- Do not use your personal SSH key to connect HCP Terraform and GitLab; generate a new one or use an existing key reserved for service access.
- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitLab.
- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them.

1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to GitLab.com. The exact command depends on your OS, but is usually something like:
   `ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise"`
   This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase.

1. While logged into the GitLab.com account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created.

1. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button.

## Finished

At this point, GitLab.com access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories.

page title  GitLab com   VCS Providers   HCP Terraform description       Learn how to use GitLab com for VCS features         Configuring GitLab com Access  These instructions are for using GitLab com for HCP Terraform s VCS features   GitLab CE and GitLab EE have separate instructions    terraform cloud docs vcs gitlab eece  as do the  other supported VCS providers    terraform cloud docs vcs   Configuring a new VCS provider requires permission to manage VCS settings for the organization    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers  Connecting HCP Terraform to your VCS involves four steps     On your VCS                                                                      On HCP Terraform                                                                                Create a new connection in HCP Terraform  Get redirect URI                    Register your HCP Terraform organization as a new app  Provide redirect URI                                                                                Provide HCP Terraform with application ID and secret  Request VCS access      Approve access request                                                                                The rest of this page explains the GitLab com versions of these steps        Note    Alternately  you can skip the OAuth configuration process and authenticate with a personal access token  This requires using HCP Terraform s API  For details  see  the OAuth Clients API page   terraform cloud docs api docs oauth clients       Step 1  On HCP Terraform  Begin Adding a New VCS Provider  1  Go to your organization s settings and then click   Providers    The   VCS Providers   page appears   1  Click   Add VCS Provider    The   VCS Providers   page appears   1  Select   GitLab   and then select   GitLab com   from the menu  The page moves to the next step   1  Locate the  Redirect URI  and copy it to your clipboard  you ll paste it in the next step   Leave the page open in a browser tab  In the next step you will copy values from this page  and in later steps you will continue configuring HCP Terraform      Step 2  On GitLab  Create a New Application  1  In a new browser tab  open  gitlab com  https   gitlab com  and log in as whichever account you want HCP Terraform to act as  For most organizations this should be a dedicated service user  but a personal account will also work           Important    The account you use for connecting HCP Terraform   must have Maintainer access   to any shared repositories of Terraform configurations  since creating webhooks requires Maintainer permissions  Refer to  the GitLab documentation  https   docs gitlab com ee user permissions html project members permissions  for details   1  Navigate to GitLab s  User Settings   Applications  https   gitlab com   profile applications  page      This page is located at  https   gitlab com   profile applications   You can also reach it through GitLab s menus        Click your profile picture and choose  Settings        Click  Applications    1  This page has a list of applications and a form for adding new ones  The form has two text fields and some checkboxes      Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab  HCP Terraform lists the values in the order they appear  and includes controls for copying values to your clipboard      Fill out the form as follows        Field                     Value                                                                                Name                      HCP Terraform    YOUR ORGANIZATION NAME                                                               Redirect URI               https   app terraform io  YOUR CALLBACK URL    the redirect URI you copied from HCP Terraform        Confidential  checkbox        enabled                                                                                Scopes  all checkboxes    api                                                                                1  Click the  Save application  button  which creates the application and takes you to its page   1  Leave this page open in a browser tab  In the next step  you will copy and paste the unique   Application ID   and   Secret        Step 3  On HCP Terraform  Set up Your Provider  1  Enter the   Application ID   and   Secret   from the previous step  as well as an option   Name   for this VCS connection   1  Click   Connect and continue    This takes you to a page on GitLab com  which asks if you want to authorize the app   1  Click the green   Authorize   button at the bottom of the authorization page      Step 4  On HCP Terraform  Configure Advanced Settings  Optional   The settings in this section are optional  The Advanced Settings you can configure are      Scope of VCS Provider     You can configure which workspaces can use repositories from this VCS provider  By default the   All Projects   option is selected  meaning this VCS provider is available to be used by all workspaces in the organization      Set up SSH Keypair     Most organizations will not need to add an SSH key  However  if the organization repositories include Git submodules that can only be accessed via SSH  an SSH key can be added along with the OAuth credentials  You can add or update the SSH key at a later time       If You Don t Need to Configure Advanced Settings   1  Click the   Skip and Finish   button  This returns you to HCP Terraform s VCS Provider page  which now includes your new GitLab client       If You Need to Limit the Scope of this VCS Provider   1  Select the   Selected Projects   option and use the text field that appears to search for and select projects to enable  All current and future workspaces for any selected projects can use repositories from this VCS Provider    1  Click the   Update VCS Provider   button to save your selections       If You Do Need an SSH Keypair        Important Notes    SSH will only be used to clone Git submodules  All other Git operations will still use HTTPS    Do not use your personal SSH key to connect HCP Terraform and GitLab  generate a new one or use an existing key reserved for service access    In the following steps  you must provide HCP Terraform with the private key  Although HCP Terraform does not display the text of the key to users after it is entered  it retains it and will use it when authenticating to GitLab      Protect this private key carefully    It can push code to the repositories you use to manage your infrastructure  Take note of your organization s policies for protecting important credentials and be sure to follow them   1  On a secure workstation  create an SSH keypair that HCP Terraform can use to connect to GitLab com  The exact command depends on your OS  but is usually something like      ssh keygen  t rsa  m PEM  f   Users  NAME   ssh service terraform   C  service terraform enterprise      This creates a  service terraform  file with the private key  and a  service terraform pub  file with the public key  This SSH key   must have an empty passphrase    HCP Terraform cannot use SSH keys that require a passphrase   1  While logged into the GitLab com account you want HCP Terraform to act as  navigate to the SSH Keys settings page  add a new SSH key and paste the value of the SSH public key you just created   1  In HCP Terraform s   Add VCS Provider   page  paste the text of the   SSH private key   you just created  and click the   Add SSH Key   button      Finished  At this point  GitLab com access for HCP Terraform is fully configured  and you can create Terraform workspaces based on your organization s shared repositories


terraform page title GitHub Enterprise VCS Providers HCP Terraform These instructions are for using a self hosted installation of GitHub Enterprise for HCP Terraform s VCS features GitHub com has separate instructions terraform cloud docs vcs github enterprise as do the other supported VCS providers terraform cloud docs vcs Learn how to use an on premise installation of GitHub Enterprise for VCS features Configuring GitHub Enterprise Access

Answer:
---
page_title: GitHub Enterprise - VCS Providers - HCP Terraform
description: >-
  Learn how to use an on-premise installation of GitHub Enterprise for VCS features.
---

# Configuring GitHub Enterprise Access

These instructions are for using a self-hosted installation of GitHub Enterprise for HCP Terraform's VCS features. [GitHub.com has separate instructions,](/terraform/cloud-docs/vcs/github-enterprise) as do the [other supported VCS providers.](/terraform/cloud-docs/vcs)

Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Connecting HCP Terraform to your VCS involves four steps:

| On your VCS                                                                                | On HCP Terraform                                            |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|                                                                                | Create a new connection in HCP Terraform. Get callback URL. |
| Register your HCP Terraform organization as a new app. Provide callback URL. Get ID and key. |                                                               |
|                                                                                | Provide HCP Terraform with ID and key. Request VCS access.  |
| Approve access request.                                                                        |                                                               |

The rest of this page explains the GitHub Enterprise versions of these steps.

~> **Important:** HCP Terraform needs to contact your GitHub Enterprise instance during setup and during normal operation. For the SaaS version of HCP Terraform, this means GitHub Enterprise must be internet-accessible; for Terraform Enterprise, you must have network connectivity between your Terraform Enterprise and GitHub Enterprise instances.

-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/cloud-docs/api-docs/oauth-clients).

## Step 1: On HCP Terraform, begin adding a new VCS provider

1. Go to your organization's settings and then click **Providers** in the Version Control section. The **VCS Providers** page appears.

1. Click **Add a VCS provider**. The **Add VCS Provider** page appears.

1. Select **GitHub** and then select **GitHub Enterprise** from the menu. The page moves to the next step.

1. In the "Set up provider" step, fill in the **HTTP URL** and **API URL** of your GitHub Enterprise instance, as well as an optional **Name** for this VCS connection.

   | Field    | Value                                       |
   | -------- | ------------------------------------------- |
   | HTTP URL | `https://<GITHUB INSTANCE HOSTNAME>`        |
   | API URL  | `https://<GITHUB INSTANCE HOSTNAME>/api/v3` |

Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform.

## Step 2: On GitHub, create a new OAuth application

1. In a new browser tab, open your GitHub Enterprise instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work.

   ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions.

1. Navigate to GitHub's Register a New OAuth Application page.

   This page is located at `https://<GITHUB INSTANCE HOSTNAME>/settings/applications/new`. You can also reach it through GitHub's menus:

   - Click your profile picture and choose "Settings."
   - Click "OAuth Apps" (under the "Developer settings" section).
   - Click the "Register a new application" button.

1. This page has a form with four text fields.

   Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard.

   Fill out the text fields as follows:

   | Field name                 | Value                                                                         |
   | -------------------------- | ----------------------------------------------------------------------------- |
   | Application Name           | HCP Terraform (`<YOUR ORGANIZATION NAME>`)                                  |
   | Homepage URL               | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) |
   | Application Description    | Any description of your choice.                                               |
   | Authorization callback URL | `https://app.terraform.io/<YOUR CALLBACK URL>`                                |

1. Click the "Register application" button, which creates the application and takes you to its page.

1. Download this image of the HCP Terraform logo and upload it with the "Upload new logo" button or the drag-and-drop target. This optional step helps you identify HCP Terraform's pull request checks at a glance.

1. Click the "Generate a new client secret" button. You will need this secret in the next step.

1. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Client ID** and **Client Secret.**

## Step 3: On HCP Terraform, set up your provider

1. Enter the **Client ID** and **Client Secret** from the previous step.

1. Click "Connect and continue." This takes you to a page on your GitHub Enterprise instance, asking whether you want to authorize the app.

1. The authorization page lists any GitHub organizations this account belongs to. If there is a **Request** button next to the organization that owns your Terraform code repositories, click it now. Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization's access restrictions.  See [About OAuth App access restrictions](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions).

   If it results in a 500 error, it usually means HCP Terraform was unable to reach your GitHub Enterprise instance.

1. Click the green "Authorize `<GITHUB USER>`" button at the bottom of the authorization page. GitHub might request your password or multi-factor token to confirm the operation.

## Step 4: On HCP Terraform, configure advanced settings (optional)

The settings in this section are optional. The Advanced Settings you can configure are:
- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization.
- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time.

### If you don't need to configure advanced settings:

1. Click the **Skip and finish** button. This returns you to HCP Terraform's VCS Providers page, which now includes your new GitHub Enterprise client.

### If you need to limit the scope of this VCS provider:

1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider.

1. Click the **Update VCS Provider** button to save your selections.

### If you need an SSH keypair:

#### Important notes

- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS.
- Do not use your personal SSH key to connect HCP Terraform and GitHub Enterprise; generate a new one or use an existing key reserved for service access.
- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitHub Enterprise.
- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them.

1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Github Enterprise. The exact command depends on your OS, but is usually something like:
   `ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise"`
   This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase.

1. While logged into the GitHub Enterprise account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created.

1. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button.

## Step 5: Contact Your GitHub organization admins

If your organization uses OAuth app access restrictions, you had to click a **Request** button when authorizing HCP Terraform, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before HCP Terraform can access your organization's shared repositories.

If you're a GitHub administrator, check your email now and respond to the request; otherwise, contact whoever is responsible for GitHub accounts in your organization, and wait for confirmation that they've approved your request.

## Finished

At this point, GitHub access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared GitHub Enterprise repositories.

page title  GitHub Enterprise   VCS Providers   HCP Terraform description       Learn how to use an on premise installation of GitHub Enterprise for VCS features         Configuring GitHub Enterprise Access  These instructions are for using a self hosted installation of GitHub Enterprise for HCP Terraform s VCS features   GitHub com has separate instructions    terraform cloud docs vcs github enterprise  as do the  other supported VCS providers    terraform cloud docs vcs   Configuring a new VCS provider requires permission to manage VCS settings for the organization    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers  Connecting HCP Terraform to your VCS involves four steps     On your VCS                                                                                On HCP Terraform                                                                                Create a new connection in HCP Terraform  Get callback URL      Register your HCP Terraform organization as a new app  Provide callback URL  Get ID and key                                                                                Provide HCP Terraform with ID and key  Request VCS access       Approve access request                                                                                The rest of this page explains the GitHub Enterprise versions of these steps        Important    HCP Terraform needs to contact your GitHub Enterprise instance during setup and during normal operation  For the SaaS version of HCP Terraform  this means GitHub Enterprise must be internet accessible  for Terraform Enterprise  you must have network connectivity between your Terraform Enterprise and GitHub Enterprise instances        Note    Alternately  you can skip the OAuth configuration process and authenticate with a personal access token  This requires using HCP Terraform s API  For details  see  the OAuth Clients API page   terraform cloud docs api docs oauth clients       Step 1  On HCP Terraform  begin adding a new VCS provider  1  Go to your organization s settings and then click   Providers   in the Version Control section  The   VCS Providers   page appears   1  Click   Add a VCS provider    The   Add VCS Provider   page appears   1  Select   GitHub   and then select   GitHub Enterprise   from the menu  The page moves to the next step   1  In the  Set up provider  step  fill in the   HTTP URL   and   API URL   of your GitHub Enterprise instance  as well as an optional   Name   for this VCS connection        Field      Value                                                                                HTTP URL    https    GITHUB INSTANCE HOSTNAME                 API URL     https    GITHUB INSTANCE HOSTNAME  api v3     Leave the page open in a browser tab  In the next step you will copy values from this page  and in later steps you will continue configuring HCP Terraform      Step 2  On GitHub  create a new OAuth application  1  In a new browser tab  open your GitHub Enterprise instance and log in as whichever account you want HCP Terraform to act as  For most organizations this should be a dedicated service user  but a personal account will also work           Important    The account you use for connecting HCP Terraform   must have admin access   to any shared repositories of Terraform configurations  since creating webhooks requires admin permissions   1  Navigate to GitHub s Register a New OAuth Application page      This page is located at  https    GITHUB INSTANCE HOSTNAME  settings applications new   You can also reach it through GitHub s menus        Click your profile picture and choose  Settings        Click  OAuth Apps   under the  Developer settings  section        Click the  Register a new application  button   1  This page has a form with four text fields      Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab  HCP Terraform lists the values in the order they appear  and includes controls for copying values to your clipboard      Fill out the text fields as follows        Field name                   Value                                                                                Application Name             HCP Terraform    YOUR ORGANIZATION NAME                                            Homepage URL                  https   app terraform io   or the URL of your Terraform Enterprise instance         Application Description      Any description of your choice                                                       Authorization callback URL    https   app terraform io  YOUR CALLBACK URL                                     1  Click the  Register application  button  which creates the application and takes you to its page   1   a href  https   content hashicorp com api assets product terraform docs common version main asset website img docs hcp terraform logo on white png  download Download this image of the HCP Terraform logo  a  and upload it with the  Upload new logo  button or the drag and drop target  This optional step helps you identify HCP Terraform s pull request checks at a glance   1  Click the  Generate a new client secret  button  You will need this secret in the next step   1  Leave this page open in a browser tab  In the next step  you will copy and paste the unique   Client ID   and   Client Secret        Step 3  On HCP Terraform  set up your provider  1  Enter the   Client ID   and   Client Secret   from the previous step   1  Click  Connect and continue   This takes you to a page on your GitHub Enterprise instance  asking whether you want to authorize the app   1  The authorization page lists any GitHub organizations this account belongs to  If there is a   Request   button next to the organization that owns your Terraform code repositories  click it now  Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization s access restrictions   See  About OAuth App access restrictions  https   docs github com en organizations managing oauth access to your organizations data about oauth app access restrictions       If it results in a 500 error  it usually means HCP Terraform was unable to reach your GitHub Enterprise instance   1  Click the green  Authorize   GITHUB USER    button at the bottom of the authorization page  GitHub might request your password or multi factor token to confirm the operation      Step 4  On HCP Terraform  configure advanced settings  optional   The settings in this section are optional  The Advanced Settings you can configure are      Scope of VCS Provider     You can configure which workspaces can use repositories from this VCS provider  By default the   All Projects   option is selected  meaning this VCS provider is available to be used by all workspaces in the organization      Set up SSH Keypair     Most organizations will not need to add an SSH key  However  if the organization repositories include Git submodules that can only be accessed via SSH  an SSH key can be added along with the OAuth credentials  You can add or update the SSH key at a later time       If you don t need to configure advanced settings   1  Click the   Skip and finish   button  This returns you to HCP Terraform s VCS Providers page  which now includes your new GitHub Enterprise client       If you need to limit the scope of this VCS provider   1  Select the   Selected Projects   option and use the text field that appears to search for and select projects to enable  All current and future workspaces for any selected projects can use repositories from this VCS Provider    1  Click the   Update VCS Provider   button to save your selections       If you need an SSH keypair        Important notes    SSH will only be used to clone Git submodules  All other Git operations will still use HTTPS    Do not use your personal SSH key to connect HCP Terraform and GitHub Enterprise  generate a new one or use an existing key reserved for service access    In the following steps  you must provide HCP Terraform with the private key  Although HCP Terraform does not display the text of the key to users after it is entered  it retains it and will use it when authenticating to GitHub Enterprise      Protect this private key carefully    It can push code to the repositories you use to manage your infrastructure  Take note of your organization s policies for protecting important credentials and be sure to follow them   1  On a secure workstation  create an SSH keypair that HCP Terraform can use to connect to Github Enterprise  The exact command depends on your OS  but is usually something like      ssh keygen  t rsa  m PEM  f   Users  NAME   ssh service terraform   C  service terraform enterprise      This creates a  service terraform  file with the private key  and a  service terraform pub  file with the public key  This SSH key   must have an empty passphrase    HCP Terraform cannot use SSH keys that require a passphrase   1  While logged into the GitHub Enterprise account you want HCP Terraform to act as  navigate to the SSH Keys settings page  add a new SSH key and paste the value of the SSH public key you just created   1  In HCP Terraform s   Add VCS Provider   page  paste the text of the   SSH private key   you just created  and click the   Add SSH Key   button      Step 5  Contact Your GitHub organization admins  If your organization uses OAuth app access restrictions  you had to click a   Request   button when authorizing HCP Terraform  which sent an automated email to the administrators of your GitHub organization  An administrator must approve the request before HCP Terraform can access your organization s shared repositories   If you re a GitHub administrator  check your email now and respond to the request  otherwise  contact whoever is responsible for GitHub accounts in your organization  and wait for confirmation that they ve approved your request      Finished  At this point  GitHub access for HCP Terraform is fully configured  and you can create Terraform workspaces based on your organization s shared GitHub Enterprise repositories


terraform These instructions are for using dev azure com for HCP Terraform s VCS features Other supported VCS providers terraform cloud docs vcs have separate instructions page title Azure DevOps Services VCS Providers HCP Terraform Configuring Azure DevOps Services Access Learn how to use Azure DevOps Services dev azure com for VCS features

Answer:
---
page_title: Azure DevOps Services - VCS Providers - HCP Terraform
description: >-
  Learn how to use Azure DevOps Services (dev.azure.com) for VCS features.
---

# Configuring Azure DevOps Services Access

These instructions are for using `dev.azure.com` for HCP Terraform's VCS features. [Other supported VCS providers](/terraform/cloud-docs/vcs) have separate instructions.

This page explains the four main steps required to connect HCP Terraform to your Azure DevOps Services VCS:

1. Create a new connection in HCP Terraform and get the callback URL.
1. On your VCS, register your HCP Terraform organization as a new application. Provide the callback URL and get the application ID and key.
1. Provide HCP Terraform with the application ID and key. Then, request VCS access.
1. On your VCS, approve the access request from HCP Terraform.

~> **Important:** HCP Terraform only supports Azure DevOps connections that use the `dev.azure.com` domain. If your Azure DevOps project uses the older `visualstudio.com` domain, you must migrate using the [steps in the Microsoft documentation](https://docs.microsoft.com/en-us/azure/devops/release-notes/2018/sep-10-azure-devops-launch#switch-existing-organizations-to-use-the-new-domain-name-url).

## Requirements

Configuring a new VCS provider requires permission to [manage VCS settings](/terraform/cloud-docs/users-teams-organizations/permissions#manage-vcs-settings) for the organization.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Before you begin, enable `Third-party application access via OAuth` in Azure DevOps Services settings.

1. Log in to [Azure DevOps Services](https://dev.azure.com/).
1. Click **Organization settings**.
1. Click **Policies** under **Security**.
1. Enable the **Third-party application access via OAuth** setting.

   ![Azure DevOps Services Screenshot: Policies Third-party application access via Oauth](/img/docs/azure-devops-services-oauth-policies.png)

## Step 1: On HCP Terraform, Begin Adding a New VCS Provider

1. Go to your organization's settings and then click **Providers**. The **VCS Providers** page appears.

1. Click **Add VCS Provider**. The **VCS Providers** page appears.

1. Select **Azure DevOps** and then select **Azure DevOps Services** from the menu. The page moves to the next step.

Leave this page open in a browser tab. You will copy values from this page into Azure DevOps in the next step, and in later steps you will continue configuring HCP Terraform.

## Step 2: From your Azure DevOps Services Profile, Create a New Application

1. In a new browser tab, open your [Azure DevOps Services Profile](https://aex.dev.azure.com), and log in to your Azure DevOps Services account if necessary. A page with a list of your organizations appears.

   ~> **Important:** The Azure DevOps Services account you use for connecting HCP Terraform must have Project Collection Administrator access to any projects containing repositories of Terraform configurations, since creating webhooks requires admin permissions. It is not possible to create custom access roles with lower levels of privilege, as Microsoft does not currently allow delegation of this capability. If you're unable to load the link above, you can create a new application for the next step at one of the following links: `https://aex.dev.azure.com/app/register?mkt=en-US` or `https://app.vsaex.visualstudio.com/app/register?mkt=en-US`.

1. Go into your preferred organization.

1. Click your user icon and then click the **ellipses (...) ** and select **User settings**.

1. From the User settings menu, click **Profile**. Your profile page appears.

1. Click **Authorizations**. The Authorized OAuth Apps page appears.

1. Click the link to register a new app. A form appears asking for your company and application information.

1. Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear and includes controls for copying values to your clipboard. Here is an example:

   | Field name                 | Value                                                                         |
   | -------------------------- | ----------------------------------------------------------------------------- |
   | Company name               | HashiCorp                                                                     |
   | Application Name           | HCP Terraform (`<YOUR ORGANIZATION NAME>`)                                  |
   | Application website        | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) |
   | Authorization callback URL | `https://app.terraform.io/<YOUR CALLBACK URL>`                                |

   In the **Authorized scopes** section, select only **Code (read)** and **Code (status)** and then click **Create Application.**

   ![Azure DevOps Services Screenshot: Required permissions when creating a new application in your Azure DevOps Services Profile](/img/docs/azure-devops-services-application-permissions.png)

   ~> **Important:** Do not add any additional scopes beyond **Code (read)** and **Code (status),** as this can prevent HCP Terraform from connecting. Note that these authorized scopes cannot be updated after the application is created; to fix incorrect scopes you must delete and re-create the application.

1. After creating the application, the next page displays its details. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **App ID** and **Client Secret** from this page.

   If you accidentally close this details page and need to find it later, you can reach it from the **Applications and Services** links in your profile.

## Step 3: On HCP Terraform, Set up Your Provider

1. (Optional) Enter a **Name** for this VCS connection.

1. Enter your Azure DevOps Services application's **App ID** and **Client Secret**. These can be found in the application's details, which should still be open in the browser tab from Step 2.

1. Click **Connect and continue.** This takes you to a page on Azure DevOps Services, asking whether you want to authorize the app. Click the **Accept** button and you'll be redirected back to HCP Terraform.

   -> **Note:** If you receive a 404 error from Azure DevOps Services, it likely means your callback URL has not been configured correctly.

## Step 4: On HCP Terraform, Configure Advanced Settings (Optional)

The settings in this section are optional. The Advanced Settings you can configure are:
- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization.
- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time.

### If You Don't Need to Configure Advanced Settings:

1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new Azure DevOps Services client.

### If You Need to Limit the Scope of this VCS Provider:

1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider.

1. Click the **Update VCS Provider** button to save your selections.

### If You Do Need an SSH Keypair:

#### Important Notes

- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS.
- Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Services; generate a new one or use an existing key reserved for service access.
- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to Azure DevOps Services.
- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them.

1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Azure DevOps Services.com. The exact command depends on your OS, but is usually something like:
   `ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise"`
   This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase.

1. While logged into the Azure DevOps Services account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created.

1. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button.

## Finished

At this point, Azure DevOps Services access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's repositories.

page title  Azure DevOps Services   VCS Providers   HCP Terraform description       Learn how to use Azure DevOps Services  dev azure com  for VCS features         Configuring Azure DevOps Services Access  These instructions are for using  dev azure com  for HCP Terraform s VCS features   Other supported VCS providers   terraform cloud docs vcs  have separate instructions   This page explains the four main steps required to connect HCP Terraform to your Azure DevOps Services VCS   1  Create a new connection in HCP Terraform and get the callback URL  1  On your VCS  register your HCP Terraform organization as a new application  Provide the callback URL and get the application ID and key  1  Provide HCP Terraform with the application ID and key  Then  request VCS access  1  On your VCS  approve the access request from HCP Terraform        Important    HCP Terraform only supports Azure DevOps connections that use the  dev azure com  domain  If your Azure DevOps project uses the older  visualstudio com  domain  you must migrate using the  steps in the Microsoft documentation  https   docs microsoft com en us azure devops release notes 2018 sep 10 azure devops launch switch existing organizations to use the new domain name url       Requirements  Configuring a new VCS provider requires permission to  manage VCS settings   terraform cloud docs users teams organizations permissions manage vcs settings  for the organization    permissions citation    intentionally unused   keep for maintainers  Before you begin  enable  Third party application access via OAuth  in Azure DevOps Services settings   1  Log in to  Azure DevOps Services  https   dev azure com    1  Click   Organization settings    1  Click   Policies   under   Security    1  Enable the   Third party application access via OAuth   setting        Azure DevOps Services Screenshot  Policies Third party application access via Oauth   img docs azure devops services oauth policies png      Step 1  On HCP Terraform  Begin Adding a New VCS Provider  1  Go to your organization s settings and then click   Providers    The   VCS Providers   page appears   1  Click   Add VCS Provider    The   VCS Providers   page appears   1  Select   Azure DevOps   and then select   Azure DevOps Services   from the menu  The page moves to the next step   Leave this page open in a browser tab  You will copy values from this page into Azure DevOps in the next step  and in later steps you will continue configuring HCP Terraform      Step 2  From your Azure DevOps Services Profile  Create a New Application  1  In a new browser tab  open your  Azure DevOps Services Profile  https   aex dev azure com   and log in to your Azure DevOps Services account if necessary  A page with a list of your organizations appears           Important    The Azure DevOps Services account you use for connecting HCP Terraform must have Project Collection Administrator access to any projects containing repositories of Terraform configurations  since creating webhooks requires admin permissions  It is not possible to create custom access roles with lower levels of privilege  as Microsoft does not currently allow delegation of this capability  If you re unable to load the link above  you can create a new application for the next step at one of the following links   https   aex dev azure com app register mkt en US  or  https   app vsaex visualstudio com app register mkt en US    1  Go into your preferred organization   1  Click your user icon and then click the   ellipses          and select   User settings     1  From the User settings menu  click   Profile    Your profile page appears   1  Click   Authorizations    The Authorized OAuth Apps page appears   1  Click the link to register a new app  A form appears asking for your company and application information   1  Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab  HCP Terraform lists the values in the order they appear and includes controls for copying values to your clipboard  Here is an example        Field name                   Value                                                                                Company name                 HashiCorp                                                                            Application Name             HCP Terraform    YOUR ORGANIZATION NAME                                            Application website           https   app terraform io   or the URL of your Terraform Enterprise instance         Authorization callback URL    https   app terraform io  YOUR CALLBACK URL                                        In the   Authorized scopes   section  select only   Code  read    and   Code  status    and then click   Create Application          Azure DevOps Services Screenshot  Required permissions when creating a new application in your Azure DevOps Services Profile   img docs azure devops services application permissions png           Important    Do not add any additional scopes beyond   Code  read    and   Code  status     as this can prevent HCP Terraform from connecting  Note that these authorized scopes cannot be updated after the application is created  to fix incorrect scopes you must delete and re create the application   1  After creating the application  the next page displays its details  Leave this page open in a browser tab  In the next step  you will copy and paste the unique   App ID   and   Client Secret   from this page      If you accidentally close this details page and need to find it later  you can reach it from the   Applications and Services   links in your profile      Step 3  On HCP Terraform  Set up Your Provider  1   Optional  Enter a   Name   for this VCS connection   1  Enter your Azure DevOps Services application s   App ID   and   Client Secret    These can be found in the application s details  which should still be open in the browser tab from Step 2   1  Click   Connect and continue    This takes you to a page on Azure DevOps Services  asking whether you want to authorize the app  Click the   Accept   button and you ll be redirected back to HCP Terraform           Note    If you receive a 404 error from Azure DevOps Services  it likely means your callback URL has not been configured correctly      Step 4  On HCP Terraform  Configure Advanced Settings  Optional   The settings in this section are optional  The Advanced Settings you can configure are      Scope of VCS Provider     You can configure which workspaces can use repositories from this VCS provider  By default the   All Projects   option is selected  meaning this VCS provider is available to be used by all workspaces in the organization      Set up SSH Keypair     Most organizations will not need to add an SSH key  However  if the organization repositories include Git submodules that can only be accessed via SSH  an SSH key can be added along with the OAuth credentials  You can add or update the SSH key at a later time       If You Don t Need to Configure Advanced Settings   1  Click the   Skip and Finish   button  This returns you to HCP Terraform s VCS Provider page  which now includes your new Azure DevOps Services client       If You Need to Limit the Scope of this VCS Provider   1  Select the   Selected Projects   option and use the text field that appears to search for and select projects to enable  All current and future workspaces for any selected projects can use repositories from this VCS Provider    1  Click the   Update VCS Provider   button to save your selections       If You Do Need an SSH Keypair        Important Notes    SSH will only be used to clone Git submodules  All other Git operations will still use HTTPS    Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Services  generate a new one or use an existing key reserved for service access    In the following steps  you must provide HCP Terraform with the private key  Although HCP Terraform does not display the text of the key to users after it is entered  it retains it and will use it when authenticating to Azure DevOps Services      Protect this private key carefully    It can push code to the repositories you use to manage your infrastructure  Take note of your organization s policies for protecting important credentials and be sure to follow them   1  On a secure workstation  create an SSH keypair that HCP Terraform can use to connect to Azure DevOps Services com  The exact command depends on your OS  but is usually something like      ssh keygen  t rsa  m PEM  f   Users  NAME   ssh service terraform   C  service terraform enterprise      This creates a  service terraform  file with the private key  and a  service terraform pub  file with the public key  This SSH key   must have an empty passphrase    HCP Terraform cannot use SSH keys that require a passphrase   1  While logged into the Azure DevOps Services account you want HCP Terraform to act as  navigate to the SSH Keys settings page  add a new SSH key and paste the value of the SSH public key you just created   1  In HCP Terraform s   Add VCS Provider   page  paste the text of the   SSH private key   you just created  and click the   Add SSH Key   button      Finished  At this point  Azure DevOps Services access for HCP Terraform is fully configured  and you can create Terraform workspaces based on your organization s repositories


terraform Configuring GitHub com Access OAuth Learn how to use GitHub com for VCS features using a per organization OAuth connection with the permissions of an individual GitHub user page title GitHub com OAuth VCS Providers HCP Terraform These instructions are for using GitHub com for HCP Terraform s VCS features using a per organization OAuth connection with the permissions of one particular GitHub user GitHub Enterprise has separate instructions terraform enterprise vcs github enterprise as do the other supported VCS providers terraform enterprise vcs

Answer:
---
page_title: GitHub.com (OAuth) - VCS Providers - HCP Terraform
description: >-
  Learn how to use GitHub.com for VCS features, using a per-organization OAuth connection with the permissions of an individual GitHub user.
---

# Configuring GitHub.com Access (OAuth)

These instructions are for using GitHub.com for HCP Terraform's VCS features, using a per-organization OAuth connection with the permissions of one particular GitHub user. [GitHub Enterprise has separate instructions,](/terraform/enterprise/vcs/github-enterprise) as do the [other supported VCS providers.](/terraform/enterprise/vcs)

For new users on HCP Terraform, we recommend using our [configuration-free GitHub App](/terraform/cloud-docs/vcs/github-app) to access repositories instead.

For Terraform Enterprise site admins, you can create your own [GitHub App](/terraform/enterprise/admin/application/github-app-integration) to access repositories.

Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Connecting HCP Terraform to your VCS involves four steps:

| On your VCS                                                                    | On HCP Terraform                                            |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
|                                                                                | Create a new connection in HCP Terraform. Get callback URL. |
| Register your HCP Terraform organization as a new app. Provide callback URL. |                                                               |
|                                                                                | Provide HCP Terraform with ID and key. Request VCS access.  |
| Approve access request.                                                        |                                                               |

The rest of this page explains the GitHub versions of these steps.

-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/cloud-docs/api-docs/oauth-clients).

## Step 1: On HCP Terraform, begin adding a new VCS provider

1. Go to your organization's settings and then click **Providers** in the **Version Control** section. The **VCS Providers** page appears.

1. Click **Add a VCS provider**. The **Add VCS Provider** page appears.

1. Select **GitHub** and then select **GitHub.com (Custom)** from the menu. The page moves to the next step.

Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform.

## Step 2: On GitHub, create a new OAuth application

On the HCP Terraform **Add VCS Provider** page, click **register a new OAuth Application**. This opens GitHub.com in a new browser tab with the OAuth application settings pre-filled.

Alternately, create the OAuth application manually on GitHub.com.

### Manual steps

1. In a new browser tab, open [github.com](https://github.com) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work.

   ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions.

1. Navigate to GitHub's [Register a New OAuth Application](https://github.com/settings/applications/new) page.

   This page is located at <https://github.com/settings/applications/new>. You can also reach it through GitHub's menus:

   - Click your profile picture and choose "Settings."
   - Click "Developer settings," then make sure you're on the "OAuth Apps" page (not "GitHub Apps").
   - Click the "New OAuth App" button.

1. This page has a form with four text fields.

   Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard.

   Fill out the text fields as follows:

   | Field name                 | Value                                                                         |
   | -------------------------- | ----------------------------------------------------------------------------- |
   | Application Name           | HCP Terraform (`<YOUR ORGANIZATION NAME>`)                                  |
   | Homepage URL               | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) |
   | Application Description    | Any description of your choice.                                               |
   | Authorization callback URL | `https://app.terraform.io/<YOUR CALLBACK URL>`                                |

### Register the OAuth application

1. Click the "Register application" button, which creates the application and takes you to its page.

1. Download this image of the HCP Terraform logo and upload it with the "Upload new logo" button or the drag-and-drop target. This optional step helps you identify HCP Terraform's pull request checks at a glance.

1. Click the **Generate a new client secret** button. You will need this secret in the next step.

1. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Client ID** and **Client Secret.**

## Step 3: On HCP Terraform, set up your provider

1. Enter the **Client ID** and **Client Secret** from the previous step, as well as an optional **Name** for this VCS connection.

1. Click "Connect and continue." This takes you to a page on GitHub.com, asking whether you want to authorize the app.

1. The authorization page lists any GitHub organizations this account belongs to. If there is a **Request** button next to the organization that owns your Terraform code repositories, click it now. Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization's access restrictions.  See [About OAuth App access restrictions](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions).

1. Click the green "Authorize `<GITHUB USER>`" button at the bottom of the authorization page. GitHub might request your password or multi-factor token to confirm the operation.

## Step 4: On HCP Terraform, configure advanced settings (optional)

The settings in this section are optional. The Advanced Settings you can configure are:
- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization.
- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time.

### If you don't need to configure advanced settings:

1. Click the **Skip and finish** button. This returns you to HCP Terraform's **VCS Providers** page, which now includes your new GitHub client.

### If you need to limit the scope of this VCS provider:

1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider.

1. Click the **Update VCS Provider** button to save your selections.

### If you need an SSH keypair:

#### Important notes

- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS.
- Do not use your personal SSH key to connect HCP Terraform and GitHub; generate a new one or use an existing key reserved for service access.
- In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, it retains it and will use it when authenticating to GitHub.
- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them.

1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to GitHub.com. The exact command depends on your OS, but is usually something like:
   `ssh-keygen -t rsa -m PEM -f "/Users/<NAME>/.ssh/service_terraform" -C "service_terraform_enterprise"`
   This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase.

1. While logged into the GitHub.com account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created.

1. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button.

## Step 5: Contact your GitHub organization admins

If your organization uses OAuth app access restrictions, you had to click a **Request** button when authorizing HCP Terraform, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before HCP Terraform can access your organization's shared repositories.

If you're a GitHub administrator, check your email now and respond to the request; otherwise, contact whoever is responsible for GitHub accounts in your organization, and wait for confirmation that they've approved your request.

## Finished

At this point, GitHub access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared GitHub repositories.

page title  GitHub com  OAuth    VCS Providers   HCP Terraform description       Learn how to use GitHub com for VCS features  using a per organization OAuth connection with the permissions of an individual GitHub user         Configuring GitHub com Access  OAuth   These instructions are for using GitHub com for HCP Terraform s VCS features  using a per organization OAuth connection with the permissions of one particular GitHub user   GitHub Enterprise has separate instructions    terraform enterprise vcs github enterprise  as do the  other supported VCS providers    terraform enterprise vcs        BEGIN  TFC only     For new users on HCP Terraform  we recommend using our  configuration free GitHub App   terraform cloud docs vcs github app  to access repositories instead       END  TFC only      For Terraform Enterprise site admins  you can create your own  GitHub App   terraform enterprise admin application github app integration  to access repositories   Configuring a new VCS provider requires permission to manage VCS settings for the organization    More about permissions    terraform enterprise users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers  Connecting HCP Terraform to your VCS involves four steps     On your VCS                                                                      On HCP Terraform                                                                                Create a new connection in HCP Terraform  Get callback URL      Register your HCP Terraform organization as a new app  Provide callback URL                                                                                Provide HCP Terraform with ID and key  Request VCS access       Approve access request                                                                                The rest of this page explains the GitHub versions of these steps        Note    Alternately  you can skip the OAuth configuration process and authenticate with a personal access token  This requires using HCP Terraform s API  For details  see  the OAuth Clients API page   terraform cloud docs api docs oauth clients       Step 1  On HCP Terraform  begin adding a new VCS provider  1  Go to your organization s settings and then click   Providers   in the   Version Control   section  The   VCS Providers   page appears   1  Click   Add a VCS provider    The   Add VCS Provider   page appears   1  Select   GitHub   and then select   GitHub com  Custom    from the menu  The page moves to the next step   Leave the page open in a browser tab  In the next step you will copy values from this page  and in later steps you will continue configuring HCP Terraform      Step 2  On GitHub  create a new OAuth application  On the HCP Terraform   Add VCS Provider   page  click   register a new OAuth Application    This opens GitHub com in a new browser tab with the OAuth application settings pre filled   Alternately  create the OAuth application manually on GitHub com       Manual steps  1  In a new browser tab  open  github com  https   github com  and log in as whichever account you want HCP Terraform to act as  For most organizations this should be a dedicated service user  but a personal account will also work           Important    The account you use for connecting HCP Terraform   must have admin access   to any shared repositories of Terraform configurations  since creating webhooks requires admin permissions   1  Navigate to GitHub s  Register a New OAuth Application  https   github com settings applications new  page      This page is located at  https   github com settings applications new   You can also reach it through GitHub s menus        Click your profile picture and choose  Settings        Click  Developer settings   then make sure you re on the  OAuth Apps  page  not  GitHub Apps         Click the  New OAuth App  button   1  This page has a form with four text fields      Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab  HCP Terraform lists the values in the order they appear  and includes controls for copying values to your clipboard      Fill out the text fields as follows        Field name                   Value                                                                                Application Name             HCP Terraform    YOUR ORGANIZATION NAME                                            Homepage URL                  https   app terraform io   or the URL of your Terraform Enterprise instance         Application Description      Any description of your choice                                                       Authorization callback URL    https   app terraform io  YOUR CALLBACK URL                                         Register the OAuth application  1  Click the  Register application  button  which creates the application and takes you to its page   1   a href  https   content hashicorp com api assets product terraform docs common version main asset website img docs hcp terraform logo on white png  download Download this image of the HCP Terraform logo  a  and upload it with the  Upload new logo  button or the drag and drop target  This optional step helps you identify HCP Terraform s pull request checks at a glance   1  Click the   Generate a new client secret   button  You will need this secret in the next step   1  Leave this page open in a browser tab  In the next step  you will copy and paste the unique   Client ID   and   Client Secret        Step 3  On HCP Terraform  set up your provider  1  Enter the   Client ID   and   Client Secret   from the previous step  as well as an optional   Name   for this VCS connection   1  Click  Connect and continue   This takes you to a page on GitHub com  asking whether you want to authorize the app   1  The authorization page lists any GitHub organizations this account belongs to  If there is a   Request   button next to the organization that owns your Terraform code repositories  click it now  Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization s access restrictions   See  About OAuth App access restrictions  https   docs github com en organizations managing oauth access to your organizations data about oauth app access restrictions    1  Click the green  Authorize   GITHUB USER    button at the bottom of the authorization page  GitHub might request your password or multi factor token to confirm the operation      Step 4  On HCP Terraform  configure advanced settings  optional   The settings in this section are optional  The Advanced Settings you can configure are      Scope of VCS Provider     You can configure which workspaces can use repositories from this VCS provider  By default the   All Projects   option is selected  meaning this VCS provider is available to be used by all workspaces in the organization      Set up SSH Keypair     Most organizations will not need to add an SSH key  However  if the organization repositories include Git submodules that can only be accessed via SSH  an SSH key can be added along with the OAuth credentials  You can add or update the SSH key at a later time       If you don t need to configure advanced settings   1  Click the   Skip and finish   button  This returns you to HCP Terraform s   VCS Providers   page  which now includes your new GitHub client       If you need to limit the scope of this VCS provider   1  Select the   Selected Projects   option and use the text field that appears to search for and select projects to enable  All current and future workspaces for any selected projects can use repositories from this VCS Provider    1  Click the   Update VCS Provider   button to save your selections       If you need an SSH keypair        Important notes    SSH will only be used to clone Git submodules  All other Git operations will still use HTTPS    Do not use your personal SSH key to connect HCP Terraform and GitHub  generate a new one or use an existing key reserved for service access    In the following steps  you must provide HCP Terraform with the private key  Although HCP Terraform does not display the text of the key to users after it is entered  it retains it and will use it when authenticating to GitHub      Protect this private key carefully    It can push code to the repositories you use to manage your infrastructure  Take note of your organization s policies for protecting important credentials and be sure to follow them   1  On a secure workstation  create an SSH keypair that HCP Terraform can use to connect to GitHub com  The exact command depends on your OS  but is usually something like      ssh keygen  t rsa  m PEM  f   Users  NAME   ssh service terraform   C  service terraform enterprise      This creates a  service terraform  file with the private key  and a  service terraform pub  file with the public key  This SSH key   must have an empty passphrase    HCP Terraform cannot use SSH keys that require a passphrase   1  While logged into the GitHub com account you want HCP Terraform to act as  navigate to the SSH Keys settings page  add a new SSH key and paste the value of the SSH public key you just created   1  In HCP Terraform s   Add VCS Provider   page  paste the text of the   SSH private key   you just created  and click the   Add SSH Key   button      Step 5  Contact your GitHub organization admins  If your organization uses OAuth app access restrictions  you had to click a   Request   button when authorizing HCP Terraform  which sent an automated email to the administrators of your GitHub organization  An administrator must approve the request before HCP Terraform can access your organization s shared repositories   If you re a GitHub administrator  check your email now and respond to the request  otherwise  contact whoever is responsible for GitHub accounts in your organization  and wait for confirmation that they ve approved your request      Finished  At this point  GitHub access for HCP Terraform is fully configured  and you can create Terraform workspaces based on your organization s shared GitHub repositories