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.

• To register an app on a personal account, visit: https://github.com/settings/apps/new.

• To register an app on an organization account, visit: https://github.com/organizations/ORGANIZATION/settings/apps/new. Replace ORGANIZATION with the name of the organization where you’d like to register the app.

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 “Pulumi ESC: Store and Retrieve 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}

Inputs

GHLoginGHE

Outputs