Authenticating to Git
OrgFlow needs to authenticate to your Git repository in order to do things like commit and push Salesforce metadata. OrgFlow uses only pure Git commands to interact with Git (i.e. no third-party or provider-specific APIs are used). This allows OrgFlow to support any Git repository.
If your Git repository requires authentication (and most will), you will need to ensure that OrgFlow can authenticate to it. How Git authentication works depends on where you are running OrgFlow operations: in OrgFlow's cloud or using the OrgFlow CLI on devices or infrastructure managed by you.
OrgFlow's cloud
Jobs and other operations initiated through the OrgFlow web app execute on managed infrastructure in OrgFlow's cloud. OrgFlow's cloud can authenticate to remote Git repositories using either a username and password, or a personal access token (PAT).
For most commercial Git providers, a personal access token (PAT) is the only supported option (the PAT is given as the password, while the username is irrelevant can typically be set to any non-empty value). For internal or self-hosted Git services, username and password may be supported.
Authentication using SSH keys are currently not supported in OrgFlow's cloud.
The credentials used for authentication are taken from your stack. This means that, to support operations in OrgFlow's cloud, you need to have valid Git credentials saved in your stack.
If you create a stack using the OrgFlow web app, you will be prompted to provide Git credentials during the stack creation process. These credentials as then saved in the stack for use later on.
If you create a stack using the OrgFlow CLI, Git credentials won't be saved in OrgFlow's cloud automatically. If you create a stack this way but intend on running jobs through the web app (in OrgFlow's cloud) you'll need to explicitly save credentials on the stack.
Securely storing Git credentials
Git credentials saved in OrgFlow's cloud are encrypted.
For teams with very strict security or compliance needs, it is also possible to never make any connections to your Git repository from our infrastructure at all, though this significantly restricts the functionality available through the OrgFlow web app. See self-hosting for more information.
OrgFlow CLI
Git authentication using the OrgFlow CLI works differently compared to OrgFlow's cloud - the CLI does not explicitly perform any authentication to your Git repository, and therefore does not use the Git credentials saved in your stack. Instead, it implicitly utilizes whatever authentication is configured on the device that you are running the CLI on.
Rule of thumb: If you are able to clone, pull, and push to the remote repository (without Git prompting for authentication) using a terminal on the device you intend to run the OrgFlow CLI on, then the OrgFlow CLI will be able to do so too.
How you configure Git authentication on the device is up to you. The most appropriate method will depend on context and your preferences:
Local computer
For local computer scenarios, especially when your repository is hosted by a commercial Git provider, the easiest and most popular way is to use Git Credential Manager. Another popular way (though more technically advanced) is to use SSH keys, which is fully supported when using the OrgFlow CLI.
CI/CD platforms
For CI/CD platforms scenarios where your Git repository and the agent/runner are colocated (such as GitHub Actions or Azure Pipelines) Git authentication is often either preconfigured by the CI/CD platform and provided transparently, or can be easily configured using built-in functionality.
Other ephemeral scenarios
For other server- or cloud-based scenarios where the agent/runner might be ephemeral, and Git authentication is not provided automatically by the platform, you will need to make sure Git authentication is configured each time the agent/runner starts up, and you cannot rely on Git's interactive authentication prompts in such contexts.
How you achieve this will depend on context and platform capabilities, but it will usually involve running a script early on in the pipeline to configure Git authentication.
The way we recommend is to use a personal access token (PAT) stored as a secret and provided to your script or pipeline as a parameter, and then using a method known as "The Simplest Bullet" in the beginning of your script or pipeline to configure transparent Git authentication.
Here's an example assuming the repository is in GitHub and we have a PAT stored in the $TOKEN variable:
shellscript
# Handle all 3 styles of Git URL as authenticated HTTPS URLs:
git config --global url."https://api:$TOKEN@github.com/".insteadOf "https://github.com/"
git config --global url."https://ssh:$TOKEN@github.com/".insteadOf "ssh://git@github.com/"
git config --global url."https://git:$TOKEN@github.com/".insteadOf "git@github.com:"Another popular way is to use SSH keys, which is fully supported when using the OrgFlow CLI.
Managing saved credentials
Git credentials saved in OrgFlow's cloud for a stack can be managed from the stack settings page.
Choosing a Git user account
OrgFlow needs a Git user account with sufficient permissions to carry out the following tasks in your Git repository:
- Clone the repository (read)
- Push commits (write)
- Optional: Force push (needed for snapshots and rollback functionality)
- Optional: Create and delete branches (needed unless you create/delete all environment branches manually)
If you have advanced security or compliance needs, and your Git provider supports it, you can use branch policies or other security mechanisms to limit permissions to only a subset of branches that OrgFlow actively uses. You will need to make sure that the user can perform the necessary actions against all of the branches in your OrgFlow stack.
Creating personal access tokens (PATs)
Most Git providers support personal access tokens (PATs) in one way or another. How to create access tokens varies by provider. Here are links to instructions for some commonly used commercial providers:
If you provider's access tokens have scopes then you'll need to ensure that the correct scopes are selected. Available scopes and their meanings differ between providers.
Consider access token expiration
Pay close attention to the expiration date of the access tokens that you create. When an access token expires you will need to create a new one and update any saved Git credentials in OrgFlow accordingly. Choose a duration that's long enough to be practical and not risk frequent disruptions, but not long enough to constitute a security risk.