Stacks

A stack in OrgFlow essentially serves two purposes:

1. It represents a bridge between your Salesforce production org and your Git repository.
2. It represents a container for a set of related Salesforce environments between which you'd like to flow metadata changes.

A stack contains:

• Settings for connecting to a Git repository
• Settings for connecting to a Salesforce production org
• One or more environments (including your production environment and any sandbox environments)
• Settings for which and how metadata should be stored, processed and flowed between environments
• Settings for selecting which API version to use when connecting to Salesforce
• History of jobs, test runs and schedules

At least one stack is needed to do any meaningful work in OrgFlow. In most cases you will only need a single stack, but you can also have several stacks in your workspace, for different purposes.

Git connection

The stack's Git connection tells OrgFlow how to connect and authenticate to your Git repository. The Git repository is used by OrgFlow for version control of your Salesforce metadata and for moving metadata changes between environments.

Providing a Git repository

OrgFlow does not include a Git repository - you must provide one yourself. Although the Git repository is utilized by OrgFlow for the purposes mentioned above, it is owned and managed by you. Learn more in our architecture overview section.

Choosing a Git provider

OrgFlow supports any standard Git repository, including those from popular commercial Git providers such as GitHub, Azure Repos, GitLab, BitBucket and others.

If you have advanced security or compliance needs, you can also use a self-hosted Git server as long as it's accessible from the public Internet and supports standard username/password authentication. For more information see our in-depth sections about Git authentication and self-hosting scenarios.

Providing connection details

When configuring the Git connection you provide the following information:

• Repository HTTP URL
  • This is often shown in relation to a "clone" action
  • Most providers offer a choice between HTTP and SSH protocols; OrgFlow supports only HTTP, so choose the corresponding URL
• Username
• Password or access token

How you obtain these values depends on your Git provider. Most commercial Git providers do not support authenticating from external tools using an actual username and password, but instead require the use of a personal access token. Separate steps are usually required to create such a token.

Securely storing credentials

Your Git credentials are encrypted with a key unique to your stack stored securely in the OrgFlow cloud. See the section about encryption for more details.

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. Refer to the sections about storing credentials and self-hosting for more information.

Permissions

OrgFlow needs 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.

Using your repository outside of OrgFlow

It's important to understand that OrgFlow does not require exclusive control over your Git repository. We encourage you to also directly interact with your Git repository alongside OrgFlow as needed. For example, you should feel free to:

• Manually commit changes to OrgFlow's environment branches (for example using an IDE such as Visual Studio Code)
• Create branches other than those used by OrgFlow, and even merge those into OrgFlow's environment branches
• Store files in the repository other than the Salesforce metadata stored by OrgFlow

OrgFlow has been designed to coexist with other activity and contents in the repository. Files outside OrgFlow's configured metadata directory will be left alone by OrgFlow. Metadata changes committed and pushed outside of OrgFlow will be incorporated into the change flow just like changes made in your Salesforce orgs by your team's developers and admins.

Salesforce connection

The stack's Salesforce connection tells OrgFlow how to connect and authenticate to your production Salesforce org, in order to do things like manage sandboxes, retrieve and deploy metadata changes, and run Apex tests.

Choosing a user account

You must decide which user account OrgFlow should use when interacting with your Salesforce production org. This user needs sufficient permissions and licenses to retrieve and deploy metadata, manage sandboxes and run Apex tests.

If you are a system administrator in your Salesforce production org, one option is to use your own user account. This may be suitable for evaluation, experimentation or for very small teams, but it has some significant drawbacks. A more robust option is to create a new API-only production user account dedicated for this purpose.

See the section about connecting to Salesforce for more information about this, and other security considerations pertaining to choosing and managing your Salesforce credentials.

Choosing a connection method

You must also decide how OrgFlow should connect and authenticate. You have two options:

1. Use browser-based authorization to sign in to your production org in a web browser to authorize OrgFlow to connect. In this mode, whenever OrgFlow creates a new sandbox on your behalf, it will pause and wait for you to perform the sign-in and authorization in the new sandbox before it can proceed to add it to your stack. The access tokens provided by Salesforce are then stored in the OrgFlow cloud so that they can be re-used whenever OrgFlow needs to interact with the connected Salesforce org.
2. Use stored credentials (i.e. username, password and security token) to connect. In this mode, OrgFlow will be able to create and manage sandboxes without the need for any user intervention.

Securely storing credentials

Your Salesforce credentials are encrypted with a key unique to your stack and stored securely in the OrgFlow cloud. See the section about encryption for more details.

For teams with very strict security or compliance needs, it is also possible to never make any connections to your Salesforce environments from our infrastructure at all, though this significantly restricts the functionality available through the OrgFlow web app. Refer to the sections about storing credentials and self-hosting for more information.

Providing sign-in values

When configuring the Salesforce connection you provide the following sign-in values:

• Username
• Optionally:
  • Custom sign-in URL (see below)
  • Password
  • Security token (depending on your Salesforce security settings - see security token considerations for more information)

The custom sign-in URL of your production org is typically something similar to https://[company].my.salesforce.com. It is also known as your "My Domain". If you don't provide a custom sign-in URL, OrgFlow will try to use the legacy sign-in URL https://login.salesforce.com to connect to your production org and find your custom sign-in URL automatically. However, it is recommended that you provide your custom sign-in URL if possible; the legacy sign-in URLs may still work, but Salesforce discourages their use and, depending on your Salesforce security settings, they may have been disabled.

If you choose to use browser-based authorization, you will need to go through the authorization flow once for each new sandbox environment that you add to your stack, to authorize OrgFlow to connect to it.

If you choose to use stored credentials, then by default, OrgFlow assumes that the production user that you provide here will also exist in any sandbox environment. Based on this assumption, OrgFlow is normally able to use these sign-in values to connect to your sandboxes also, by transforming them based on the sandbox name. You also have the option to provide specific sign-in values for individual environments if you need to.

Environments

As mentioned above, a stack is a group of related environments. Each environment consists of a Salesforce org (production or sandbox) and a backing Git branch. You can learn more in our dedicated section about environments.

All the environments in the same stack have several things in common:

• Environments in a stack belong to the same Salesforce production org. A stack maps one-to-one with a production org, and can only contain that production org and sandboxes belonging to that production org. Sandboxes belonging to other production orgs do not belong in the same stack.

• Environments in a stack share the same Git repository. Each environment in a stack is backed by a branch in that repository. Your production environment is typically backed by the main or master branch, while sandbox environments are backed by feature branches with names that you decide.

• Environments in a stack share a single metadata "code base" and will contain temporarily diverging but ultimately converging versions of that single code base. While development work is on-going, the environments in a stack will have differences, but there is an expectation that those differences will ultimately be reconciled as branches are merged and integrated changes are deployed to downstream environments. This aligns naturally with sandboxes sharing the same production org and branches in the same Git repository.

• Environments in a stack can have metadata changes flowed between them. In OrgFlow, metadata changes are always flowed from one environment to another by merging between branches in the Git repository. If you intend to flow changes between any two environments, they must be in the same stack. (Though technically changes can of course also be ultimately propagated between different stacks through a shared production environment.)

• Environments in a stack share a common configuration. You can customize which subset of metadata you want OrgFlow to track, keep in your Git repository and flow between the environments in the stack. You can also customize certain settings for how metadata is versioned and processed. All such settings are configured on a per-stack basis and are the same for all environments in the stack.

Environments which are not conceptually related in the ways described above do not belong in the same stack. As you can see there are several potential reasons why you might need more than one stack to support your Salesforce DevOps needs.

A stack is unstructured

It's important to understand that, while the environments in a stack are all related, they do not form an inherent structure within the stack. All environments in a stack are equivalent, and you can flow changes between any two environments as you see fit. There is no concept of downstream or upstream relationships between any particular environments, and no constraints forcing users to propagate or promote changes in any particular stages. The word "stack" itself refers to the concept of an unstructured collection of environments (usually visualized in OrgFlow as a vertical list resembling a stack of boxes).

Metadata settings

Included metadata

A stack includes filtering rules for which subset of your Salesforce metadata that should be included in the flow. These filtering rules are stored in a file named .orgflowinclude in the root of the Git repository.

Metadata that matches the filtering rules is included in OrgFlow's automatic change detection, stored in your Git repository and flowed between the environments in your stack. Any metadata not matching the filtering rules is ignored by OrgFlow and will never be stored in your Git repository.

See the section about managing included metadata to learn more.

Version control settings

Additionally, a stack includes version control settings that you can use to customize how and where OrgFlow stores metadata in your repository. See the section on understanding metadata version control to learn more.

Salesforce API settings

A stack also includes settings that let you control how OrgFlow selects which API version to use when connecting to different Salesforce orgs in the stack.

This can affect the format and structure of the metadata retrieved from Salesforce and stored in different branches of your repository. It can also impact your ability to flow metadata between your environments, especially during Salesforce preview windows when some sandboxes may be on a preview version of Salesforce while other sandboxes (and your production org) are not.

These settings can also be overridden for individual environments.

See the section about managing API versions to learn more.

Using multiple stacks

The majority of teams support only a single production org with a single code base and a release pipeline. Such teams will normally only need a single stack in their workspace. However, some example scenarios where your team might need more than one stack include:

• Supporting more than one production org. If your company owns multiple production Salesforce orgs (perhaps for different departments or as a result of M&A) you can use multiple stacks to support them. (But remember to ensure that you comply with the terms of your OrgFlow license, which normally stipulate that you can use a single license only to support a single business.)

• Separating different DevOps needs. For example, you might use one stack to drive your change management and release pipeline. This stack would contain your production environment as well as all your development sandbox environments, and might only include a subset of your org's metadata. In addition you might have another stack, backed by different Git repository, to schedule regular commits of your production metadata to Git. This stack might contain only your production environment, but include all metadata, even types that you don't normally flow between environments such as dashboards and reports.