> For the complete documentation index, see [llms.txt](https://docs.flosum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flosum.com/devops/getting-started/onboarding-with-devops.md).
# Onboarding with DevOps
{% hint style="warning" %}
#### Written for the Old UI
This article was written for the old UI. The instructions are still usable, but the screenshots are outdated. In some cases, items referenced in the instructions have moved or changed. If you cannot find an item, see the [Where Did It Go](/devops/new-ui-ux-transition/where-did-it-go.md) article.
{% endhint %}
##  Overview
When the DevOps app is opened for the first time, Flosum automatically launches the onboarding guide. The guide continues to appear until you skip or complete it, and once skipped or completed, it cannot be run again. Onboarding introduces DevOps by walking you through the core setup tasks needed to get started, from connecting your Salesforce orgs to running your first deployment. Each step includes guided instructions and context, so you can complete the process in a single, structured session without prior DevOps experience. This article provides insight and help for each step of the onboarding process.
{% hint style="info" %}
Before starting the onboarding process, make sure you have access to two Salesforce orgs and can make changes to at least one. During the onboarding process, you will retrieve components from one org and deploy a selection of those components to the other org. For information on the requirements for connecting a Salesforce org to DevOps, see the following article.
{% endhint %}
The diagram below provides a visual overview of the onboarding process, showing each step you will complete and the order in which they occur.
### Skip Onboarding
You are not required to complete the onboarding process before using DevOps, and you will not lose out on any functionality. You can skip the onboarding process at any point in the process.
1. Click **Skip onboarding** in the lower left of the screen.
## Onboarding Steps
{% hint style="info" %}
The DevOps onboarding process guides you through setting up DevOps and deploying components to a Salesforce org. This guide provides helpful information to support onboarding and includes example screenshots for each completed step.
{% endhint %}
{% stepper %}
{% step %}
### What Is Your Role
This step lets you select the role that best matches your current job. The role you select does not affect onboarding or DevOps functionality. Flosum uses your answer for internal analytics to improve the DevOps app, and it does not include personally identifiable information.
1. Select one of the roles that best matches your role.
2. Click **Next**.
{% endstep %}
{% step %}
### What Is Your Objective For Using DevOps
This step lets you describe what you hope to accomplish with DevOps. What you write does not affect onboarding or DevOps functionality. Flosum uses your answer for internal analytics to improve the DevOps app, and it does not include personally identifiable information.
1. Enter the DevOps goals you want to achieve.
2. Click **Next**.
{% endstep %}
{% step %}
### Connect Your Source Salesforce Org
This step connects one of your Salesforce orgs to DevOps. The Salesforce org you connect to will be used as the **Source Organization** during the onboarding process. This means you will add components from this organization to a branch that will be deployed to a target organization.
**Create Connection**
1. In the **Organization name** textbox, enter a descriptive name for the Salesforce org you are connecting to.
2. Click the **Environment** dropdown menu and select the environment type for this organization.
{% hint style="info" %}
The Environment selection helps you identify the organization's primary use, but it does not restrict how the organization can be used. Below is a general description of each environment.
* **Dev**: Where developers build and test new features.
* **Prod**: The live environment used by real customers.
* **Test**: For validating changes before release.
* **QA**: For structured testing and release sign-off.
{% endhint %}
3. Select the **Organization type** for the Salesforce org you are connecting to: **Production** or **Sandbox**.
4. Click **Connect**.
**Log in to Salesforce**
{% hint style="info" %}
When connecting a Salesforce org, it is recommended to use a dedicated user. For more information on creating a dedicated user, please refer to the following article.
[Creating a Dedicated Salesforce User](/global-settings/environment/organizations/creating-a-dedicated-salesforce-user.md)
{% endhint %}
1. You will be directed to a Salesforce login screen.
2. In the **Username** textbox, enter the username of a user with Admin privileges in the Salesforce org you are connecting to.
3. In the **Password** textbox, enter the Salesforce user's password.
4. Click **Log In**.
5. If Salesforce prompts you to **Allow Access** to Flosum:
1. Review the items listed in the access request.
2. Click **Allow**.
**Finish**
{% hint style="info" %}
If you need to use a different organization or change login information:
* Click the **Trash Can** icon to delete the organization.
* Repeat the **Connect Source Organization** step.
{% endhint %}
1. Once successfully connected, you will see the organization listed in **Connected organization**.
2. Click **Next**.
{% endstep %}
{% step %}
### Connect Your Target Salesforce Org
This step connects another one of your Salesforce orgs to DevOps. The Salesforce org you connect to will be used as the **Target Organization** during the onboarding process. This means you will deploy components from a branch to this organization.
**Create Connection**
1. In the **Organization name** textbox, enter a descriptive name for the Salesforce org you are connecting to.
2. Click the **Environment** dropdown menu and select the environment type for this organization.
{% hint style="info" %}
The Environment selection helps you identify the organization's primary use, but it does not restrict how the organization can be used. Below is a general description of each environment.
* **Dev**: Where developers build and test new features.
* **Prod**: The live environment used by real customers.
* **Test**: For validating changes before release.
* **QA**: For structured testing and release sign-off.
{% endhint %}
3. Select the **Organization type** for the Salesforce org you are connecting to: **Production** or **Sandbox**.
4. Click **Connect**.
**Log in to Salesforce**
{% hint style="info" %}
When connecting a Salesforce org, it is recommended to use a dedicated user. For more information on creating a dedicated user, please refer to the following article.
[Creating a Dedicated Salesforce User](/global-settings/environment/organizations/creating-a-dedicated-salesforce-user.md)
{% endhint %}
1. You will be directed to a Salesforce login screen.
2. In the **Username** textbox, enter the username of a user with Admin privileges in the Salesforce org you are connecting to.
3. In the **Password** textbox, enter the Salesforce user's password.
4. Click **Log In**.
5. If Salesforce prompts you to **Allow Access** to Flosum:
1. Review the items listed in the access request.
2. Click **Allow**.
**Finish**
{% hint style="info" %}
If you need to use a different organization or change login information:
* Click the **Trash Can** icon to delete the organization.
* Repeat the **Connect Target Organization** step.
{% endhint %}
1. Once successfully connected, you will see the organization listed in **Connected organization**.
2. Click **Next**.
{% endstep %}
{% step %}
### Invite Your Team
This step allows you to create Flosum Cloud Apps user accounts for your teammates so they can use DevOps. Any users added in this step will receive an invitation email with login instructions and a temporary password.
{% hint style="info" %}
The user you create in this step will have the System Administrator role. Later, you can change the user’s role and add more users in Global Settings. To learn more about user management in Flosum Cloud Apps, see the following article.
* [Overview of Roles, Groups, and Users](/global-settings/user-management/overview-of-roles-groups-and-users.md)
{% endhint %}
{% hint style="warning" %}
The **Email** address for any user added in this step must be one they can access so they can receive login instructions and a temporary password.
{% endhint %}
**Add Suggested User**
For convenience, the onboarding process checks the Salesforce orgs you connected in the previous steps and suggests users you may want to create accounts for.
1. Browse or search the **Suggestions** table to add users.
2. Click the **Add** button to the right of any user to create an account for them.
**Add Any Users**
1. Click **Add Teammate** to add a new user row.
2. Enter the user's **First name**, **Last** **name**, and **Email**.
**Finish**
Once all users are added:
1. Click **Invite**.
2. The onboarding process will create the accounts and send invitation emails.
{% endstep %}
{% step %}
### Create a New Branch
This step creates a new branch for your codebase. In the following steps, you will add components from your source organization to this branch, then deploy the branch to your target organization.
1. In the **New branch name** textbox, enter a descriptive name. Follow your team’s branch naming guidelines.
2. In the **Source branch** dropdown, the only option is **main**. All DevOps tenants start with only the main branch. Later, you can create additional branches and select an existing branch as the source.
3. Click **Create**.
{% endstep %}
{% step %}
### Retrieve
This step retrieves metadata from your **Source Organization**, allowing you to select what to include in your branch in the following steps. To speed up the retrieval, only ApexClass, ApexTrigger, CustomObject, CustomField, RecordType, and FieldSet Components are retrieved; this process may take a few minutes.
{% hint style="info" %}
This process may take a few minutes, depending on the number of components retrieved. For large retrieve jobs, the status may update to **Partially Complete**, at which point you can proceed to the next step. However, if the component you want to add to your branch has not yet been retrieved, you must wait until the retrieve job status is updated to **Completed**.
{% endhint %}
1. Wait for this job to complete.
2. Click **Next**.
{% hint style="warning" %}
If issues are found during retrieval, it is not recommended that you proceed with onboarding.
1. Click **Skip onboarding** in the lower left corner.
{% endhint %}
{% endstep %}
{% step %}
### Retrieved Components
This step displays the components that DevOps retrieved from your **Source Organization**. No action is required at this stage. You can browse, filter, and search the component list to review what was retrieved. Click any component to view its contents.
{% hint style="info" %}
Because the onboarding process does not retrieve all components, you might not see every component in your Salesforce org. After onboarding is complete, run a full retrieve to get the remaining components.
{% endhint %}
1. Click **Next**.
{% endstep %}
{% step %}
### Commit Metadata To Your Branch
This step commits selected components to the branch you created in a previous step. You can select any available component to add to the branch. These components will later be deployed to your target branch. Because a typical Salesforce org has thousands of components, it is recommended to use the search and filter features to find the components you want to add. The screenshot below demonstrates adding a single component to the branch.
1. Search and filter to find the component you want to add.
1. Use the **Search** box to search for components by name.
2. Click the **Select Type** dropdown to filter the list of components by type.
2. Click **Add** next to the component you want to add to the branch.
3. Repeat this process to add all components you want to include in this commit.
4. Once you have added all components, enter a commit message in the **Commit Message** text box.
5. Click **Commit**.
{% hint style="info" %}
The **Add all** button adds all listed components, including components on other pages in the list. If you use the **Add all** button, make sure you have carefully searched and filtered the list and verified that there are no unwanted components.
{% endhint %}
{% endstep %}
{% step %}
### Commit
This step displays the commit job log, allowing you to track the job's progress as your changes are committed to the branch.
1. Wait for the Commit Job to complete.
2. Click **Next**.
{% endstep %}
{% step %}
### Committed Components
This step allows you to view the components committed to the branch. These components will later be deployed to the target organization. You can search and filter for components. Click any component to view its contents.
1. Review the components in your branch.
2. Click **Next**.
{% endstep %}
{% step %}
### Pre-Deploy Fix
This step lets you run a Pre-Deploy Fix to validate that the components in your branch can be deployed to the target organization. During onboarding, the Pre-Deploy Fix job only checks for missing dependencies and does not allow you to resolve them. This step is optional and can be skipped.
{% hint style="info" %}
If issues are found, resolve them outside of the onboarding process. Because the Pre-Deploy Fix step is not critical, you can continue onboarding and resolve the issues after you finish. The following article explains the process for resolving issues identified by this job in depth.
* [Using Branch PreDeploy Fix](/devops/code/branch-actions/using-branch-predeploy-fix.md)
{% endhint %}
1. Click **Run Pre-Deploy Fix**.
2. Wait for the Pre-Deploy Fix job to complete.
3. Click **See results** to review the results.
4. Once you have reviewed the results, click **Next**.
{% endstep %}
{% step %}
### Validate
This step lets you run a Validate job to confirm that the components in your branch can be deployed to your target organization. Validation checks metadata compatibility, verifies dependencies, and runs Apex tests when required, but does not make changes to the target organization. Validating before deployment helps you identify and fix issues early, which reduces deployment failures. This step is optional and can be skipped.
{% hint style="info" %}
If validation finds issues, you can proceed with onboarding and still deploy the branch. After the deployment completes, you can roll it back in the next onboarding step.
{% endhint %}
1. Click **Run Validate**.
2. Wait for the Validate job to complete.
3. Click **Next**.
{% hint style="warning" %}
The next step automatically starts the **Deploy** job, deploying the branch components to the target organization.
{% endhint %}
{% endstep %}
{% step %}
### Deploy
This step deploys the components in your branch to the **Target Organization**. The Deploy job starts automatically and may take several minutes. After deployment, the job runs default tests to verify that the deployment succeeded. In the next step, you can undo the deployment by rolling back the changes in the target organization.
1. Wait for the Deploy job to complete.
2. Click **Next**.
{% endstep %}
{% step %}
### Rollback
This step allows you to roll back the changes deployed to your Target Organization in the previous step. The Rollback job may take several minutes and uses a pre-deployment snapshot to reverse the changes to the organization and restore components to their previous state. This step is optional but useful if there were errors during deployment or if you do not want to deploy the branch to this organization.
1. Click **Run Rollback**.
2. Wait for the Rollback job to complete.
3. Click **Next**.
{% endstep %}
{% step %}
### You're All Set
You have finished the DevOps onboarding process. This step provides a quick overview of what you've achieved during onboarding.
1. Click **Next**.
{% endstep %}
{% step %}
### Explore More Powerful Features
There are many additional features beyond what you have configured during onboarding. This step provides a preview of advanced features and workflows in Flosum Cloud DevOps. To learn more about any of these features, follow the links below.
1. Click **Explore DevOps**.
2. You have now completed the onboarding and have access to the full DevOps app.
{% endstep %}
{% endstepper %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.flosum.com/devops/getting-started/onboarding-with-devops.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
