GitHub Provider

The GitHub provider is used to interact with GitHub resources.

The provider allows you to manage your GitHub organization's members and teams easily. It needs to be configured with the proper credentials before it can be used.

Use the navigation to the left to read about the available resources.

Example Usage

Terraform 0.13 and later:

terraform {
  required_providers {
    github = {
      source  = "integrations/github"
      version = "~> 6.0"
    }
  }
}

# Configure the GitHub Provider
provider "github" {}

# Add a user to the organization
resource "github_membership" "membership_for_user_x" {
  # ...
}

Terraform 0.12 and earlier:

# Configure the GitHub Provider
provider "github" {
  version = "~> 5.0"
}

# Add a user to the organization
resource "github_membership" "membership_for_user_x" {
  # ...
}

Authentication

The GitHub provider offers multiple ways to authenticate with GitHub API.

GitHub CLI

The GitHub provider taps into GitHub CLI authentication, where it picks up the token issued by gh auth login command. It is possible to specify the path to the gh executable in the GH_PATH environment variable, which is useful for when the GitHub Terraform provider can not properly determine its the path to GitHub CLI such as in the cygwin terminal.

OAuth / Personal Access Token

To authenticate using OAuth tokens, ensure that the token argument or the GITHUB_TOKEN environment variable is set.

provider "github" {
  token = var.token # or `GITHUB_TOKEN`
}

GitHub App Installation

To authenticate using a GitHub App installation, ensure that arguments in the app_auth block or the GITHUB_APP_XXX environment variables are set. The owner parameter required in this situation. Leaving out will throw a 403 "Resource not accessible by integration" error.

Some API operations may not be available when using a GitHub App installation configuration. For more information, refer to the list of supported endpoints.

provider "github" {
  owner = var.github_organization
  app_auth {
    id              = var.app_id              # or `GITHUB_APP_ID`
    installation_id = var.app_installation_id # or `GITHUB_APP_INSTALLATION_ID`
    pem_file        = var.app_pem_file        # or `GITHUB_APP_PEM_FILE`
  }
}
provider "github" {
  owner = var.github_organization
  app_auth {} # When using `GITHUB_APP_XXX` environment variables
}

Argument Reference

The following arguments are supported in the provider block:

Note: If you have a PEM file on disk, you can pass it in via pem_file = file("path/to/file.pem").

For backwards compatibility, if more than one of owner, organization, GITHUB_OWNER and GITHUB_ORGANIZATION are set, the first in this list takes priority.

  1. Setting organization in the GitHub provider configuration.
  2. Setting the GITHUB_ORGANIZATION environment variable.
  3. Setting the GITHUB_OWNER environment variable.
  4. Setting owner in the GitHub provider configuration.