Skip to main content
Sign in Dashboard Get started
  1. Docs
  2. Secrets & Configuration
  3. Providers
  4. Login & OIDC
  5. gh-login

gh-login

    The gh-login provider enables you to log in to GitHub using app credentials. The provider will return an installation access token that can be used to access the GitHub API and repositories.

    The provider works as a GitHub App to produce an installation access token for the specified GitHub account, as described in “Authenticating as a GitHub App installation”. Use the token with the Pulumi ESC GitHub Action, the GitHub CLI, etc. The token will expire after 1 hour.

    App Registration

    To use the provider, you must register a new GitHub App into your personal GitHub account or an organization account. Other GitHub accounts then install the application into their account to grant you access with the permissions defined by your GitHub App.

    This is different from installing the Pulumi GitHub App for Deployments and CI/CD integration, which should be installed according to the instructions in the GitHub App documentation.

    It is fine to deploy a separate GitHub app for each Pulumi environment, or to reuse an app across environments. It is recommended that you store the app’s credentials in a reusable environment that you can import as needed.

    Provider Configuration

    Configure the provider with the app ID and private key for the GitHub App that you registered. See “Generating Private Keys” for instructions on how to generate a private key (in PEM format) and download to your computer.

    Private keys do not expire and need to be manually revoked. You must keep private keys for GitHub Apps secure. Store the private key as a secret by using the fn::secret function. See “fn::secret”.

    Because the PEM-formatted private key spans multiple lines, wrap it in a YAML block scalar (|) so the newlines are preserved. See “Multi-line secrets”.

    appId: 123456
privateKey:
  fn::secret: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----

    Owner

    An installation access token is always scoped to a particular Github account, set by the environment as owner. The owner property may refer to a personal account or an organization account. The owner or app manager of the account must first install the GitHub App that was registered earlier. For more information, see “Installing your own GitHub App” and “Sharing your GitHub App”.

    owner: octocat

    Use multiple instances of the gh-login provider to create installation access tokens for multiple accounts.

    Repository Access

    By default, an installation access token has access to all repositories that the installation was granted access to. Use the repositories property to further restrict the allowed repositories. The token cannot be granted access to repositories that the installation was not granted access to. You can list up to 500 repositories.

    repositories:
  - "Spoon-Knife"
  - "Hello-World"

    Token Permissions

    Optionally, use the permissions property to specify the permissions that the installation access token should have. By default, the installation access token will have all of the permissions that were granted to the app. The installation access token cannot be granted permissions that the app was not granted.

    See “Create an installation access token for an app” for a list of permissions and associated permission levels.

    permissions:
  contents: read
  pull_requests: write

    GitHub Enterprise Server

    To access a GitHub Enterprise Server, configure the ghe.host property to your server address.

    ghe:
  host: ghe.example.com

    Example

    values:
  gh:
    fn::open::gh-login:
      # configure the app credentials
      appId: 123456
      privateKey:
        fn::secret: |
          -----BEGIN RSA PRIVATE KEY-----
          ...
          -----END RSA PRIVATE KEY-----
      # configure the target GH account for the installation access token
      owner: octocat
      # optionally restrict access to specific repos
      repositories:
        - "Spoon-Knife"
      # optionally restrict the token permissions
      permissions:
        contents: read
        pull_requests: write
  environmentVariables:
    # export the GH_TOKEN environment variable
    GH_TOKEN: ${gh.accessToken}
  pulumiConfig:
    # configure the GitHub IaC provider
    github:token: ${gh.accessToken}

    Schema reference

    Reference schemas last updated on 2026-07-11, synced automatically from the Pulumi Cloud ESC API.

    Inputs

    • appId number required
      The ID of the GitHub App providing access tokens for the environment.
    • ghe object optional
      Options for connecting to a GitHub Enterprise installation.
    • ↳ host string required
      The hostname of your GitHub Enterprise server.
    • owner string required
      The repository owner to access.
    • permissions object optional
      The permissions that the installation access token should have.
    • ↳ actions string optional
      The level of permission for actions.
    • ↳ administration string optional
      The level of permission for administration.
    • ↳ blocking string optional
      The level of permission for blocking.
    • ↳ checks string optional
      The level of permission for checks.
    • ↳ content_references string optional
      The level of permission for content_references.
    • ↳ contents string optional
      The level of permission for contents.
    • ↳ deployments string optional
      The level of permission for deployments.
    • ↳ emails string optional
      The level of permission for emails.
    • ↳ environments string optional
      The level of permission for environments.
    • ↳ followers string optional
      The level of permission for followers.
    • ↳ issues string optional
      The level of permission for issues.
    • ↳ members string optional
      The level of permission for members.
    • ↳ metadata string optional
      The level of permission for metadata.
    • ↳ organization_administration string optional
      The level of permission for organization_administration.
    • ↳ organization_hooks string optional
      The level of permission for organization_hooks.
    • ↳ organization_plan string optional
      The level of permission for organization_plan.
    • ↳ organization_pre_receive_hooks string optional
      The level of permission for organization_pre_receive_hooks.
    • ↳ organization_projects string optional
      The level of permission for organization_projects.
    • ↳ organization_secrets string optional
      The level of permission for organization_secrets.
    • ↳ organization_self_hosted_runners string optional
      The level of permission for organization_self_hosted_runners.
    • ↳ organization_user_blocking string optional
      The level of permission for organization_user_blocking.
    • ↳ packages string optional
      The level of permission for packages.
    • ↳ pages string optional
      The level of permission for pages.
    • ↳ pull_requests string optional
      The level of permission for pull_requests.
    • ↳ repository_hooks string optional
      The level of permission for repository_hooks.
    • ↳ repository_pre_receive_hooks string optional
      The level of permission for repository_pre_receive_hooks.
    • ↳ repository_projects string optional
      The level of permission for repository_projects.
    • ↳ secret_scanning_alerts string optional
      The level of permission for secret_scanning_alerts.
    • ↳ secrets string optional
      The level of permission for secrets.
    • ↳ security_events string optional
      The level of permission for security_events.
    • ↳ single_file string optional
      The level of permission for single_file.
    • ↳ statuses string optional
      The level of permission for statuses.
    • ↳ team_discussions string optional
      The level of permission for team_discussions.
    • ↳ vulnerability_alerts string optional
      The level of permission for vulnerability_alerts.
    • ↳ workflows string optional
      The level of permission for workflows.
    • privateKey string required
      The private key of the GitHub App (in PEM format).
    • repositories array[string] optional
      List of repositories to allow access to.

    Outputs

    • accessToken string required
      The access token used to authenticate with the GitHub API.
    • appId number required
      The ID of the GitHub App providing access tokens for the environment.
    • appSlug string required
      The GitHub App’s slug.
    • expiry string required
      The access token’s expiry time.
    • installationId number required
      The ID of the GitHub App installation.
    • type enum required
      The access token’s type.
      Values: installation