GitHub

Enhanced Advanced

Posit Connect supports two types of GitHub integrations:

This guide walks through the configuration process for both integration types.

Choosing an integration type

Use case Integration type
Users need to access their own GitHub resources (repos, gists) Viewer (OAuth App)
Content needs automated access without user interaction GitHub App
Scheduled reports or batch processing that accesses GitHub GitHub App
Interactive applications with user-specific data Viewer (OAuth App)
Note

GitHub App integrations are required for non-interactive content because Connect cannot initiate OAuth authorization flows on behalf of users without their direct interaction. When content runs without a user session (such as scheduled reports), a GitHub App provides service account-style access.

GitHub Enterprise Server

Both integration types support GitHub Enterprise Server. Use the optional GitHub Enterprise Server field to specify your GitHub Enterprise Server hostname (e.g., github.example.com). Connect will automatically derive the appropriate URLs for OAuth authorization, token exchange, and GitHub App API calls.

Viewer (OAuth App) integration

Step 1: GitHub administrator

Register a GitHub OAuth App

The GitHub administrator registers an OAuth App in GitHub. They will need the Posit Connect redirect URL which is defined as https://connect.example.org/__oauth__/integrations/callback. Replace connect.example.org with the address of the Connect server.

The Connect Administrator must obtain the client ID and client secret from the GitHub administrator. The client ID can be found under Settings > Developer settings > OAuth Apps > . A client secret can be generated at the same location.

GitHub requires Confidential authentication. Public Viewer OAuth integrations are not supported.

The GitHub administrator will control the level of access through granular Repository, Organization, and Account settings. Unlike other OAuth integrations GitHub disregards all received scopes. Further restricting access by repository_id is not supported within Connect itself but can be implemented within the content hosted on Connect.

Transfer information to Connect administrator

The GitHub administrator shares the following information with the Posit Connect administrator:

Field Description
client_id The unique identifier of the OAuth App.
client_secret The secret string used to authenticate against the OAuth App.

Step 2: Posit Connect administrator

Using the information from the GitHub administrator, the Posit Connect administrator creates an integration through the dashboard’s System > Integrations settings. Once the OAuth integration has been created in Connect, it is available for use by all publishers.

When creating the integration, select GitHub as the template and Viewer as the authentication type.

Alternatively, the example below shows how to create a GitHub OAuth integration using curl and the Connect Server API. Replace connect.example.org with the address of the Connect server.

Terminal
curl -H "Authorization: Key ${CONNECT_API_KEY}" \
  -XPOST https://connect.example.org/__api__/v1/oauth/integrations \
  --data '{
    "template": "github",
    "name": "GitHub OAuth App",
    "description": "User-delegated access to GitHub resources.",
    "config": {
      "auth_type": "Viewer",
      "client_id": "<client-id>",
      "client_secret": "<client-secret>",
      "auth_mode": "Confidential"
    }
  }'
# 200 OK
# {"guid": "<oauth-integration-guid>", ... }

GitHub App integration

GitHub App integrations allow content running on Posit Connect to access GitHub resources using installation access tokens. This is the recommended approach for service account access to GitHub.

Note

GitHub App integrations are designed for non-interactive content such as scheduled reports or batch processing jobs that need automated access to GitHub resources. For interactive applications where users need to access their own GitHub data, use the Viewer (OAuth App) integration instead.

Step 1: GitHub administrator

Create a GitHub App

The GitHub administrator creates a GitHub App in GitHub.

When creating the GitHub App:

  1. Navigate to Settings > Developer settings > GitHub Apps > New GitHub App.
  2. Provide a name and homepage URL for the app.
  3. Under Webhook, uncheck Active (webhooks are not needed for this integration).
  4. Under Permissions, configure the repository and organization permissions your content requires.
  5. Under Where can this GitHub App be installed?, select the appropriate option for your organization.

After creating the app, generate a private key:

  1. Navigate to Settings > Developer settings > GitHub Apps > .
  2. Scroll down to Private keys and click Generate a private key.
  3. Save the downloaded .pem file securely.

Install the GitHub App

After creating the app, install it on the repositories or organizations that your content needs to access:

  1. Navigate to Settings > Developer settings > GitHub Apps > .
  2. Click Install App in the sidebar.
  3. Select the account where you want to install the app.
  4. Choose whether to grant access to all repositories or select specific repositories.
  5. Click Install.

After installation, note the Installation ID from the URL. When viewing your installed app, the URL will be in the format: https://github.com/settings/installations/<installation-id>.

Transfer information to Connect administrator

The GitHub administrator shares the following information with the Posit Connect administrator:

Field Description
client_id The Client ID (not the App ID) from the GitHub App settings page. This is a 20-character alphanumeric value starting with “Iv”. Found under Settings > Developer settings > GitHub Apps > in the “About” section.
installation_id The Installation ID from the installed app URL.
private_key The contents of the .pem private key file generated for the app.

For GitHub Enterprise Server installations, you will also need to provide:

Field Description
github_host The GitHub Enterprise Server hostname (e.g., github.example.com). Leave empty for github.com.

Optional: Scope the integration

By default, the integration requests tokens with access to all repositories the GitHub App is installed on and all permissions granted to the app. For greater security, you can optionally restrict the token scope:

Field Description
repositories Space-separated list of repository names to limit token access (e.g., repo1 repo2). Leave empty to access all repositories the app is installed on.
permissions Space-separated list of permission restrictions as name:value pairs (e.g., contents:read issues:write). Leave empty to use the app’s full permissions.
Tip

Scoping tokens follows the principle of least privilege: content that only needs read access to a single repository shouldn’t get write access to all repositories. This reduces the blast radius if a token is compromised.

Step 2: Posit Connect administrator

Using the information from the GitHub administrator, the Posit Connect administrator creates an integration through the dashboard’s System > Integrations settings. Once the OAuth integration has been created in Connect, it is available for use by all publishers.

When creating the integration, select GitHub as the template and GitHub App as the authentication type.

Alternatively, the example below shows how to create a GitHub App integration using curl and the Connect Server API. Replace connect.example.org with the address of the Connect server.

Terminal
curl -H "Authorization: Key ${CONNECT_API_KEY}" \
  -XPOST https://connect.example.org/__api__/v1/oauth/integrations \
  --data '{
    "template": "github",
    "name": "GitHub App Integration",
    "description": "Service account access to GitHub for automated workflows.",
    "config": {
      "auth_type": "GitHub App",
      "client_id": "<client-id>",
      "installation_id": "<installation-id>",
      "private_key": "<private-key-pem-contents>"
    }
  }'
# 200 OK
# {"guid": "<oauth-integration-guid>", ... }

For GitHub Enterprise Server, include the github_host in the config:

Terminal
curl -H "Authorization: Key ${CONNECT_API_KEY}" \
  -XPOST https://connect.example.org/__api__/v1/oauth/integrations \
  --data '{
    "template": "github",
    "name": "GitHub Enterprise App Integration",
    "description": "Service account access to GitHub Enterprise Server.",
    "config": {
      "auth_type": "GitHub App",
      "client_id": "<client-id>",
      "installation_id": "<installation-id>",
      "private_key": "<private-key-pem-contents>",
      "github_host": "github.example.com"
    }
  }'
# 200 OK
# {"guid": "<oauth-integration-guid>", ... }

To create a scoped integration with restricted repository and permission access:

Terminal
curl -H "Authorization: Key ${CONNECT_API_KEY}" \
  -XPOST https://connect.example.org/__api__/v1/oauth/integrations \
  --data '{
    "template": "github",
    "name": "GitHub App (Read-only)",
    "description": "Read-only access to specific repositories.",
    "config": {
      "auth_type": "GitHub App",
      "client_id": "<client-id>",
      "installation_id": "<installation-id>",
      "private_key": "<private-key-pem-contents>",
      "repositories": "my-repo data-repo",
      "permissions": "contents:read"
    }
  }'
# 200 OK
# {"guid": "<oauth-integration-guid>", ... }

Test the integration

After creating the integration, you can test it from the Connect dashboard:

  1. Navigate to Integrations in the Connect dashboard.
  2. Find your GitHub App integration and click the Test button.
  3. A successful test confirms that Connect can authenticate with GitHub and obtain an installation access token.

Using the integration in content

Content can use this integration to obtain GitHub installation access tokens through the OAuth Credentials API. The tokens can be used to authenticate with the GitHub API for operations like:

  • Cloning private repositories
  • Creating issues or pull requests
  • Accessing repository contents
  • Managing GitHub Actions workflows

Installation access tokens are short-lived (typically 1 hour) and automatically scoped to the permissions configured for the GitHub App.

Next steps

Once the integration is configured, publishers can use it in their content. See the following cookbook recipes for examples: