> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/ci-cd/getting-started.md). # Getting Started This page walks through setting up codev for the first time, assuming no prior experience with Salesforce development tooling. It explains the three things every setup asks for — a repository connection, a Dev Hub, and an SFDX auth URL — and then walks through setting up CI/CD for a GitHub-backed project. The basic setup validates changes against a sandbox; scratch orgs and pools are optional on top. The shared steps (project, GitHub App, Dev Hub) look the same in every feature's setup wizard, so this guide is also the reference for those. If you already know what these are, you can go straight to [Step 1](#step-1-create-a-project). ## What you need before you start | You need | What it is | Where it comes from | | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | A codev login | Access to your organization's codev instance (`https://.flxbl.io` or your self-hosted URL) | Your codev administrator, or [flxbl.io](https://flxbl.io) for a cloud instance | | A Git repository | The repository that holds (or will hold) your Salesforce source code | GitHub or Azure DevOps. This guide uses GitHub; for Azure DevOps see [Azure DevOps](/flxbl/codev/integrations/source-control/azure-devops.md) | | A Salesforce org with Dev Hub enabled | Usually your production org, or a Developer Edition org for evaluation | See [What is a Dev Hub?](#what-is-a-dev-hub) below | | The Salesforce CLI | The `sf` command-line tool, used once during setup to produce an auth URL | [Salesforce CLI install guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm) | ## Concepts ### What is a Dev Hub? A **Dev Hub** is a Salesforce org with the Dev Hub feature turned on. Enabling it lets that org create and manage **scratch orgs** (short-lived, disposable Salesforce environments) and track **sandboxes**. codev uses your Dev Hub to provision the environments that builds, validations, and [pools](/flxbl/codev/pools/overview.md) run against. You do not create a Dev Hub from scratch — you enable the feature on an org you already have: 1. Log in to your production org (or a [Developer Edition org](https://developer.salesforce.com/signup) if you are evaluating). 2. Open **Setup**, search for **Dev Hub**. 3. Turn on **Enable Dev Hub**. If you plan to use scratch org pools, also review the active scratch org limits shown there. Enabling Dev Hub is not reversible, but it does not change any behavior of the org itself — it only allows it to manage scratch orgs and sandboxes. For the basic setup the Dev Hub is simply your production org, registered once. Validation itself runs against a **sandbox**; scratch orgs only come into play if you later adopt [pools](/flxbl/codev/pools/getting-started.md). ### What is an SFDX auth URL? An **SFDX auth URL** is a single string, starting with `force://`, that carries everything needed to authenticate to one Salesforce org — it is how you hand codev a connection to an org without sharing a password. The Salesforce CLI produces it after you log in once on your machine: ```bash # 1. Confirm the CLI is installed sf --version # 2. This opens a browser window; complete the Salesforce login there. # The CLI stores the session under the alias `my-devhub`. sf org login web --alias my-devhub # 3. Only after step 2 succeeds: print that org's auth URL sf org auth show-sfdx-auth-url --target-org my-devhub # (Already logged in earlier? `sf org list` shows your authenticated orgs # and their aliases — use one of those in step 3 instead.) ``` Step 3 works only for an org the CLI is already logged into — it prompts for confirmation, then prints the `force://...` value. That whole string is the credential you paste into codev. It is only available for orgs authorized through a web login (step 2), not the JWT flow. {% hint style="info" %} **Older CLI versions use a different command.** Before the Salesforce CLI releases of May 27, 2026, the auth URL came from `sf org display --verbose --target-org my-devhub` (the **Sfdx Auth Url** row of the output). From those releases onward that field is redacted, and `sf org auth show-sfdx-auth-url` is the supported way to retrieve it. If one command is not recognized or prints a redacted value, use the other. {% endhint %} Treat an auth URL like a password: whoever has it can act as that user in that org. codev encrypts auth URLs at rest and never shows them again after registration. Prefer logging in as a **dedicated service account** (an integration user) rather than your personal user, so the connection does not break when an individual leaves or changes their password. ### What is the GitHub App? codev works on your repository — it reads source code, posts validation results as checks, and comments on pull requests. It does this through a **GitHub App**, GitHub's mechanism for granting an application scoped access to selected repositories. On the cloud instance, GitHub is already connected through flxbl's installed GitHub App; during onboarding you only approve which repositories it can see. On a self-hosted instance you register your own app — see [GitHub](/flxbl/codev/integrations/source-control/github.md) for the full authentication reference. ## Step 1: Create a project A **project** in codev is one repository plus the branches you want codev to track. Sign in, and if this is a fresh instance you land on project creation directly; otherwise open the project selector (top left) and choose to create a new project. 1. Paste your **Repository URL** (for example `https://github.com/your-org/your-repo`). codev detects the platform and derives the **Project Identifier** from the URL. 2. Under **Branches to track**, select the branches codev should watch for merges and pull requests — typically `main`, plus any long-lived release branches. 3. Click **Create Project**.

Create New Project panel with a repository URL filled in — Creating a project: paste the repository URL, the identifier is derived automatically, pick the branches to track.

## Step 2: Activate features Creating a project lands you on the **Activate Features** page. codev is modular: each feature area (CI/CD, Pools, Inspect, Ops, and so on) is activated independently, and each card lists the setup steps it needs — steps like **App Integration** or **Dev Hub** are shared, so completing one for a feature completes it everywhere. This guide follows **CI/CD**, whose wizard covers every shared step. Each feature has its own guide at the start of its section.

Activate Features page showing the eight feature cards with their setup steps — Each feature card lists the setup steps it needs. Shared steps count for every feature that needs them.

Clicking a card opens its setup wizard, with one collapsible section per step:

Set Up CI/CD wizard with the steps App Integration, Dev Hub, Project Readiness, and Configure Webhooks — The CI/CD setup wizard: App Integration, Dev Hub, Project Readiness, Configure Webhooks.

## Step 3: Connect GitHub (App Integration) The first wizard step, **App Integration**, connects your Git provider. On the cloud instance, click **Install GitHub App**:

App Integration step on the cloud instance with the Install GitHub App and Verify Installation buttons — On the cloud instance, App Integration is two clicks: **Install GitHub App**, then **Verify Installation** once you are back.

GitHub opens its installation page for the app. This is where you choose which repositories codev can work on: pick your organization, then either **All repositories** or **Only select repositories** with the repositories you want — include at least the one you used in Step 1. Click **Install & Authorize**.

GitHub's Install and Authorize page with the Only select repositories option and the Select repositories picker — Repository access is granted on GitHub's own installation page — **Only select repositories** shows the picker. Names shown are placeholders.

Back in the wizard, click **Verify Installation** and the step marks itself complete. This is a one-time, organization-level step — the next project you create finds it already done. On a self-hosted instance there is no managed app, so the same step takes your own GitHub App's credentials instead — the **App ID** and its private key (`.pem`), both from the app's settings page on GitHub. How to create that GitHub App (and everything else about GitHub authentication) is covered on the integration page: {% content-ref url="/pages/rrvye4Rcny9hPqPUUTzH" %} [GitHub](/flxbl/codev/integrations/source-control/github.md) {% endcontent-ref %}

App Integration step showing the GitHub App credential form and a healthy connection — The App Integration step on a self-hosted instance. Once connected, the health line confirms codev can reach the repository.

## Step 4: Connect your Dev Hub The **Dev Hub** step registers your Dev Hub org with codev. Click **Connect Dev Hub**, then in the dialog choose the **SFDX Auth URL** tab: 1. On your machine, produce the auth URL with the CLI commands from [What is an SFDX auth URL?](#what-is-an-sfdx-auth-url) — the dialog also walks through this under **How to get your SFDX Auth URL** (on a current CLI, use `sf org auth show-sfdx-auth-url` where the dialog shows `sf org display --verbose`). 2. Paste the `force://...` string into the **SFDX Auth URL** field. 3. Leave **This is a Dev Hub org** checked, and click **Register Org**.

Connect Dev Hub dialog with the SFDX Auth URL field and the CLI how-to steps — The Connect Dev Hub dialog walks through producing the auth URL with the Salesforce CLI. The value shown is a placeholder.

Registered orgs are shared across all projects on the instance through [environments](/flxbl/codev/pools/overview.md), so a Dev Hub connected once serves every project. ## Step 5: Readiness check and webhooks Two steps remain in the wizard: * **Project Readiness** runs a check of your repository's structure — that it is a valid sfp project with `sfdx-project.json`, package directories, and release configs codev can build. Click **Test Readiness**; each check reports individually, and a failing check names what is missing. If the repository is not configured yet, you do not have to fix it by hand: the step offers **Configure Project**, which analyzes the repository and **opens a pull request** with the required changes (`sfdx-project.json` package entries and generated release configs). Review and merge that PR, then click **Recheck Readiness**. For how an sfp project is laid out, see the [sfp docs](https://docs.flxbl.io/flxbl). * **Configure Webhooks** subscribes codev to repository events, so a merge starts a build and a pull request starts validation without anyone triggering them by hand. Click **Configure Webhooks**; codev registers the webhook on the repository through the GitHub App.

Project Readiness step with the Test Readiness button — Project Readiness checks the repository for the configuration sfp expects.

When every step in the wizard shows complete, the feature is active. The remaining sections cover the setup that comes after: environments, pools, and the pull-request flow they enable. {% hint style="warning" %} **Server workflows are off by default.** Configuring webhooks subscribes codev to repository events, but the built-in workflows that act on them — build on merge, change validation, and change analysis — start disabled. Turn each on from its **Workflow Settings** dialog: * **Builds** page → **Enable server builds** (build on merge) * **Change Validation** page → **Enable server change validation** * **Analysis** page → **Enable server change analysis** Until a workflow is enabled, its events are received but recorded as **Skipped** — no build, validation, or analysis runs. {% endhint %} ## Step 6: Register your environments An **environment** in codev is a registered Salesforce org with a role. You register the org (its SFDX auth URL, same mechanics as the Dev Hub in Step 4), then create an environment for it under **Environments**, choosing one of three categories: | Category | Role | | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | **Test** | Receives builds automatically when code merges to the branch it tracks — the first place merged code lands | | **Snapshot** | A known-good copy of a branch, kept current — the source that sandbox pools clone from, and where hotfixes are validated | | **Release** | The formal promotion targets — staging, UAT, production | Each environment tracks a branch (an exact name or a pattern like `release/*`), which is how codev knows where a build should deploy. Use **Create**, or the **+** on a category card, name the environment, pick its category and org, and set the branch it tracks.

Environments page grouped by Test, Snapshot, and Release categories — The Environments page, grouped by category. A typical starting set: one Test, one Snapshot, and your Release environments.

{% content-ref url="/pages/n20em7jmnWA4bRLz0KGM" %} [Environments](/flxbl/codev/environments/environments.md) {% endcontent-ref %} ## From pull request to release With environments in place and the server workflows enabled (see the note above), the day-to-day flow runs on its own. When a developer opens a pull request: 1. **Change analysis and change validation start on their own** — the webhooks from Step 5 tell codev about the PR; no one triggers anything. 2. **codev assigns a review environment** — in the simplest setup a dedicated **sandbox**, or an environment drawn from a [pool](/flxbl/codev/pools/getting-started.md) — chosen by the assignment rule matching the PR's branch and the domains it touches. codev **deploys the changed packages to it and runs the Apex tests** there, before merge.

Review environments page showing assignment rules and active assignments — Assignment rules map branch and domain patterns to a pool; each open PR gets its own review environment from it.

3. **The result comes back to the pull request** as a check with pass/fail and test coverage, and the PR is labeled (`validation-succeeded` / `validation-failed`). Reviewers can open the assigned review environment to click through the change in a live org.

Change validation results with deployment and test outcomes per package — A validation run's results: what deployed, what was tested, and what failed — the same detail the PR check links to.

4. **On merge, codev builds** the affected packages into versioned artifacts, deploys them to the Test and Snapshot environments tracking that branch, and rolls them into a **release candidate**. 5. **Release**: on the Release Candidates page, click **Release**, pick the Release environment, and codev runs a dry-run validation, waits for the approval gate, then locks the environment, deploys, and unlocks.

Release dialog for a release candidate with target environment and work items — Releasing a candidate: pick the target environment; codev handles dry-run, approval, lock, deploy, unlock.

The same chain continues past the release — deployed releases, rollback, and hotfixes from a release are all one page further: {% content-ref url="/pages/Hvy9VU2TQa0cOQnKS5Cq" %} [Change Validation](/flxbl/codev/inspect/change-validation.md) {% endcontent-ref %} {% content-ref url="/pages/jkzZGV93jTADCzeuXtY3" %} [Builds](/flxbl/codev/ci-cd/overview.md) {% endcontent-ref %} {% content-ref url="/pages/oCGJeQytN9WpcDMSqOA2" %} [Managing Release Candidates](/flxbl/codev/ci-cd/managing-release-candidates.md) {% endcontent-ref %} {% content-ref url="/pages/aJ1GyYNeGFxUBqIcMTif" %} [Releases](/flxbl/codev/ci-cd/overview-3.md) {% endcontent-ref %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flxbl.io/flxbl/codev/ci-cd/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.