Git-Backed Content

Posit Connect publishers can deploy content to Connect in a variety of ways. One mechanism is to create content on Connect directly from a Git repository. The User Guide contains instructions on the steps taken by publishers.

Content deployed from a Git repository is indicated in the content’s Settings -> Info with a Git-specific section containing metadata about the source repository.

A given source repository can be associated with any number of applications.

Requirements

Note

Git >=1.7.12 is required for Git backed content.

The version of Git installed in the same environment as Posit Connect is detected at process startup time, and is subject to the PATH set in the process environment. Alternatively, the path to the git executable can be set directly via Git.Executable.

If the version of Git cannot be detected, or if the version is lower than the minimum required of 1.7.12, an error is logged and startup is aborted. See Disabling to learn how to disable Git backed content support.

Publishing

Git backed content can be associated with either public or private Git repositories, and can use https:// (recommended) or http:// remotes.

The Applications.RunAs user runs all git commands necessary for retrieving repository data.

Note

Currently, Posit Connect Git-backed publishing does not support Git Large File Storage (LFS).

Public repositories

Publicly-accessible source repositories can be configured by any user with a publisher role.

Private repositories

Private source repositories can be accessed by setting GitCredential.Host, GitCredential.Username, and GitCredential.Password, which works with any authentication based on HTTP basic auth, such as with GitHub personal access tokens.

/etc/rstudio-connect/rstudio-connect.gcfg
[GitCredential]
Host = github.com
Username = accountName
Password = <encrypted-string>
Protocol = https
Note

The encrypted string value of GitCredential.Password should be generated via rscadmin.

You can support multiple hosts by including additional GitCredential sections. Each host can only have a single credential. When configuring multiple credentials, you must name each configuration section. If multiple GitCredential share names, the last one is used.

/etc/rstudio-connect/rstudio-connect.gcfg
[GitCredential "github"]
Host = github.com
Username = accountName
Password = <encrypted-string>
Protocol = https

[GitCredential "selfhosted"]
Host = git.mycompany.com
Username = accountName
Password = <encrypted-string>
Protocol = https

Connect can also use configured Git credentials to install packages from private Git repositories during environment restoration:

  • R packages: Connect uses credentials for github.com, gitlab.com, and bitbucket.org to restore R packages from private repositories on those services. See private R packages from Git repositories for details.

  • Python packages: Connect uses credentials for all configured GitCredential hosts to install Python packages specified as Git URL dependencies in requirements.txt. See private Python packages from Git repositories for details.

OAuth authentication

Connect supports OAuth2 authentication for Git using the client credentials grant flow. Connect authenticates with Git hosting platforms using OAuth access tokens instead of static passwords or personal access tokens, providing improved security and centralized credential management.

Note

OAuth authentication for Git requires a service account OAuth integration, which uses the OAuth 2.0 Client Credentials Grant Type. Platforms like Azure DevOps support this authentication method.

Important

Bearer token authentication (the default mode when GitCredential.Username is not set) requires git 2.31 or later. This version introduced support for passing git configuration through environment variables, which Connect uses to keep OAuth tokens out of process listings for security reasons. Verify your installed git version with git --version before enabling this feature.

To use OAuth authentication for Git, you must:

  1. Configure your Git hosting platform to allow OAuth-based authentication
  2. Create a service account OAuth integration in Connect using the credentials from your platform
  3. Configure the GitCredential in Connect to reference the OAuth integration by name

OAuth with Azure DevOps

Azure DevOps supports OAuth authentication for Git operations using service principals. The following steps outline how to configure this integration.

For complete details, see Microsoft’s documentation on using service principals with Azure DevOps.

Step 1: Register an application in Entra ID

Create an app registration in the Azure portal:

  1. Navigate to Microsoft Entra ID → App registrations → New registration
  2. Enter a name for the application (e.g., “Connect Git Integration”)
  3. Select the appropriate supported account type for your organization
  4. Register the application
Step 2: Capture required values

From your app registration, note the following values:

  • Tenant ID
  • Client ID (Application ID)
  • Client secret (create one under Certificates & secrets)
  • Enterprise application object ID (found under Enterprise applications, not the app registration object ID) — this is the service principal ID used when adding to Azure DevOps
Step 3: Add the service principal to Azure DevOps

Add the Entra ID application as a service principal in Azure DevOps using the enterprise application object ID from Step 2:

  1. In Azure DevOps, navigate to Organization settings → Users
  2. Select Add users and search for the app registration name or enterprise application object ID
  3. Add the service principal with the appropriate access level (e.g., Basic)
  4. Grant the service principal access to the projects and repositories it needs
Important

Add the service principal to Azure DevOps before configuring OAuth authentication. Without this step, authentication will fail even with valid OAuth tokens.

Step 4: Create the OAuth integration in Connect

Create a service account OAuth integration in Connect with the following values from your app registration:

  • Name: The name you assign here must match the value you set in GitCredential.OAuthIntegration (e.g., my-git-oauth-integration)
  • Integration type: Custom or Azure (depending on your setup)
  • Token URL: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
  • Client ID: Your application’s client ID
  • Client secret: Your application’s client secret
  • Scopes: https://app.vssps.visualstudio.com/.default
Important

When creating the OAuth integration for Git, set the access control list (ACL) to restrict access to administrators only. This prevents publishers from accidentally associating the Git integration with published content.

Step 5: Configure Connect

Update your Connect configuration to reference the OAuth integration by its name:

/etc/rstudio-connect/rstudio-connect.gcfg
[GitCredential "azure-devops"]
Host = dev.azure.com
Protocol = https
OAuthIntegration = my-git-oauth-integration

Creating the OAuth integration for other providers

For Git hosting platforms other than Azure DevOps, create an OAuth integration in Connect with the credentials from your platform. Configure the integration as a service account type, which uses the client credentials flow to obtain access tokens.

You need the following from your Git hosting platform:

  • Client ID: The application/client identifier
  • Client secret: The application secret
  • Token endpoint URL: The OAuth token endpoint for your provider
  • Scopes: The OAuth scopes required for Git operations (provider-specific)

See the OAuth Integrations documentation for details on creating integrations.

Configuring GitCredential for OAuth

Configure Connect to use the OAuth integration by setting GitCredential.OAuthIntegration to the name of your OAuth integration:

/etc/rstudio-connect/rstudio-connect.gcfg
[GitCredential "azure-devops"]
Host = dev.azure.com
Protocol = https
OAuthIntegration = my-git-oauth-integration
Important

The value of OAuthIntegration must exactly match the name you gave the OAuth integration when you created it in Connect. Connect uses this name to look up the integration and obtain access tokens for Git authentication.

Note

When using OAuth authentication, do not set GitCredential.Password. The GitCredential.Username setting is optional; if not set, Connect uses bearer token authentication, which is the preferred method for Azure DevOps.

Automatic fetch & deploy

Git backed content differs from content that is directly published to Posit Connect, as indirect user actions such as pushing a Git commit to the associated repository can result in a new deployment. The decision to trigger a new deployment is made after a periodic fetch of the source repository, and only occurs if the specified branch and path prefix have changed since the last fetched commit.

Note

Periodic Git fetches are automatically performed at ~15 minute intervals for each Git backed application. This interval duration can be modified via the Git.PollingFrequency setting. To turn off automatic Git fetches entirely, set the value to 0.

Note

The same polling frequency interval and deployment logic are used for public and private repositories.

Operational considerations

Throughout the lifetime of managing Git backed content, various background processes can be spawned, and data written to file storage. As a result, the number and type of processes running on the system can vary independent of users interacting with Posit Connect. The size and composition of file based storage can likewise independently change over time.

Repository data

All Git repository clones and cached metadata are stored relative to the Server.DataDir at {Server.DataDir}/git.

Automatic cleanup

An automatic cleanup is triggered at startup time and periodically during runtime which is responsible for removing any Git repository data which is no longer in use. Such data includes Git repository clones which are not associated with content and temporary clones fetched prior to first deploy.

Concurrency limits

The Git.Concurrency setting limits the number of concurrent parent processes which can be spawned for Git operations. The limit is imposed at the individual Connect process level, meaning that a clustered deployment has a total concurrency that is a multiple of the cluster members.

Process management

Git operations are run in a process sandbox using the configured supervisor command, if any. It is particularly important to ensure that the supervisor command does not write anything to standard out, as this interferes in unpredictable ways with git operations. Supervisor scripts must echo all informational messages to standard error rather than standard out.

Disabling

In the case that Git backed content is not desired, such as when the Git version requirement cannot be met, it can be disabled by setting Git.Enabled to false.