bitrise-io · zoltan-baba · Jun 29, 2026 · Jun 26, 2026
@@ -13,74 +13,118 @@ Adding a <GlossTerm baseform="Project">project</GlossTerm> to Bitrise means one
 
 - Adding a new project with a CI configuration, connecting a Git repository to the project.
 
-  During the process, we also run our [project scanner](https://github.com/bitrise-steplib/steps-project-scanner) that detects the platform type of the project - for example, iOS - and generate default <GlossTerm baseform="Workflow">Workflows</GlossTerm> with all the necessary <GlossTerm baseform="Step">Steps</GlossTerm> to build and deploy an app.
+  During the process, we also run our [project scanner](https://github.com/bitrise-steplib/steps-project-scanner) that detects the platform type of the project — for example, iOS — and generate default <GlossTerm baseform="Workflow">Workflows</GlossTerm> with all the necessary <GlossTerm baseform="Step">Steps</GlossTerm> to build and deploy an app.
 - Adding a new project with a new Release Management app: [Adding a new app to Release Management](/en/release-management/getting-started-with-release-management/adding-a-new-app-to-release-management).
 
 Each Bitrise <GlossTerm baseform="project">project</GlossTerm> is owned by a [workspace](/en/bitrise-platform/workspaces/workspaces-overview).
 
 :::note[The project scanner]
 
-Supporting a platform/framework means that our project scanner can detect the type of the project and set up a basic Bitrise configuration based on the type. You can add any other project, too, regardless of how it's built but you'll have to configure it manually.
+Supporting a platform/framework means that our project scanner can detect the type of the project and set up a basic Bitrise configuration based on the type. You can add any other project, too, regardless of how it's built, but you'll have to configure it manually.
 
 :::
 
-In this guide, we'll go through how to add a new project to Bitrise.
+In this guide, we'll go through how to add a new CI project to Bitrise.
 
-1. On the **Dashboard**, click the **New project** button.
+1. On the **Dashboard**, click **New project**.
 1. Select **Configure Bitrise CI**.
 
+   ![Add CI config entry point — choose how you want to get started modal](/img/getting-started/2026-06-27-add-ci-config-dashboard-modal.png)
+
    :::tip[Release Management]
 
-   You can select **Add your app** to proceed with adding a new app to Release Management. From this point, you can follow this guide: [Adding a new app to Release Management](/en/release-management/getting-started-with-release-management/adding-a-new-app-to-release-management)
+   Select **Add your app** to add a new app to Release Management instead. See [Adding a new app to Release Management](/en/release-management/getting-started-with-release-management/adding-a-new-app-to-release-management).
 
    :::
-1. Select the Workspace that will own the project.
 
-   ![20251219-adding-project-workspace-select.png](/img/_paligo/uuid-d1d45e63-f66b-fd5d-f4af-4d893ff388fb.png)
-1. Set the project to private or public. This settings can't be changed later.
+The **Add CI config** wizard has three stages: **Repository**, **CI configuration**, and **Build settings**.
 
-   - Private projects are only accessible to the Workspace members. They need to authenticate themselves to view the project's details.
-   - [Public projects](/en/bitrise-platform/projects/public-projects) expose their configuration file and build logs to everyone who has the link.
-1. Connect a repository. You can:
+## Repository
 
-   - Connect your GitHub account or organization to Bitrise via [the GitHub App integration](/en/bitrise-platform/repository-access/github-app-integration) and select an available repository. We strongly recommend this method if you are using a GitHub repository.
-   - [Connect your Git provider account to Bitrise via an OAuth application](/en/bitrise-platform/repository-access/repository-access-with-oauth#connecting-a-git-provider-with-oauth-when-adding-a-project) and select an available repository.
+Complete each of the following sub-steps in order.
 
-     :::note
+### Connecting to your Git provider
 
-     For self-hosted GitLab or Bitbucket Server, use the dedicated menu option in the **Provider** dropdown menu. Do not paste the URL into Other.
+Under **Connect to your Git provider**, select a connection method from the **Connection method** dropdown:
 
-     :::
-   - Enter a repository URL manually.
+- **GitHub App (recommended)**: connect via the GitHub App integration. Requires your Workspace admin to configure credentials in **Workspace settings > Integrations** first. See [GitHub App integration](/en/bitrise-platform/repository-access/github-app-integration).
+- **GitHub OAuth**, **GitLab**, **Bitbucket**: connect via OAuth to your account on the respective provider. See [Repository access with OAuth](/en/bitrise-platform/repository-access/repository-access-with-oauth).
+- **[GitHub Enterprise Server](/en/bitrise-platform/repository-access/integrating-github-enterprise-with-bitrise)**, **Bitbucket Server**, **[Self-hosted GitLab](/en/bitrise-platform/repository-access/connecting-self-hosted-gitlab-instances)**: for self-hosted Git providers.
+- **Other**: connect any other Git repository by entering its URL manually.
 
-   ![20251219-repo-access.png](/img/_paligo/uuid-2970ac6b-3d97-8318-0863-aff6e1f106da.png)
-1. Configure authorization to allow Bitrise to access the repository. There are multiple ways to do so, depending on the type of your project:
+Once you select a provider, click **Connect provider** to set up the connection, or **Select repository** if the provider is already connected.
 
-   - Public projects don't require authorization.
-   - Private projects that are accessed via the [GitHub App integration](/en/bitrise-platform/repository-access/github-app-integration) don't need additional authorization.
-   - Private projects with SSH URLs, accessed via OAuth applications, require [configuring an SSH key](/en/bitrise-platform/repository-access/configuring-ssh-keys). Bitrise can do this automatically or you can create and register your own SSH key pair.
-   - Private projects with HTTPS URLs, accessed via OAuth applications, require [HTTPS authorization with a personal access token](/en/bitrise-platform/repository-access/configuring-https-authorization-credentials). We recommend using a token with only **read** access.
+![Connect to your Git provider — connection method dropdown with GitHub OAuth selected](/img/getting-started/2026-06-27-add-ci-config-connect-git-provider.png)
 
-   ![20251219-authorize-bitrise.png](/img/_paligo/uuid-cd752575-c17c-0ccd-25b3-a2c97daadd57.png)
-1. Set the default branch of the project and decide if you want our [project scanner](/en/bitrise-ci/workflows-and-pipelines/developing-your-own-bitrise-step/creating-your-own-bitrise-project-scanner) to scan the code on the branch.
+### Selecting a repository
 
-   - If your repository is connected, you can select an available branch from a dropdown menu.
-   - If you entered a repository URL manually, you need to type a valid branch name.
+Select the repository you want to connect:
 
-   :::note[Repository URL]
+- **Select from list**: use the account dropdown to filter by organization or user, then select a repository from the list. Use the search field to find a specific one.
+- **Add URL manually**: enter the repository URL directly.
 
-   You will be able to [change your project's repository URL](/en/bitrise-platform/projects/configuring-the-repository-url-and-the-default-branch) later. You can also connect or disconnect your account to Git provider services at any time.
+Click **Confirm selection**.
 
-   :::
+![Select repository — browsing repositories by account](/img/getting-started/2026-06-27-add-ci-config-select-repository.png)
+
+:::note
+
+If you can't find a repository, you may need to request org approval for the Bitrise OAuth app. The link appears below the repository list.
+
+:::
+
+### Authorizing Bitrise
+
+:::note
+
+This step is only required if you are not using the GitHub App and your repository is connected via an SSH URL. Repositories connected via HTTPS URLs do not require SSH key configuration. The wizard skips this step automatically if it is not needed.
+
+:::
+
+Choose how Bitrise accesses your repository:
+
+- **Auto-add a generated SSH key to your repository**: Bitrise adds the key automatically. Requires admin rights on your Git provider.
+- **Copy a generated SSH key to your Git provider manually**: use this if your build needs to access additional private repositories beyond the one you're connecting (for example, a private CocoaPods spec repository, Fastlane match storage, or Git submodules). Copy the generated key and add it to each repository manually.
+- **Add your own SSH key to Bitrise**: use an existing SSH key pair.
+
+For more information, see [Configuring SSH keys](/en/bitrise-platform/repository-access/configuring-ssh-keys).
+
+![Authorize Bitrise — SSH key options](/img/getting-started/2026-06-27-add-ci-config-authorize-bitrise.png)
+
+### Selecting the default branch
+
+Select the branch Bitrise will use for builds when no other configuration specifies a different one:
+
+- If your repository is connected, select a branch from the dropdown.
+- If you added a URL manually, type the branch name directly.
+
+You can [change the default branch](/en/bitrise-platform/projects/configuring-the-repository-url-and-the-default-branch) later. Click **Next** to proceed to the next stage.
+
+![Select default branch — branch dropdown with main selected](/img/getting-started/2026-06-27-add-ci-config-select-default-branch.png)
+
+## CI configuration
+
+Bitrise scans your repository and generates a starter CI configuration automatically.
+
+![CI configuration — scanning repository](/img/getting-started/2026-06-27-add-ci-config-ci-configuration-scanning.png)
+
+Once scanning completes:
+
+- If a project type is detected, it appears under the **Detected options** tab.
+- If no project type is detected, switch to the **Manual setup** tab and select your project type from the **Project type** dropdown. Supported types include Android, Cordova, Fastlane, Flutter, Ionic, iOS, and others.
+
+![CI configuration — manual project type selection](/img/getting-started/2026-06-27-add-ci-config-project-type-picker.png)
+
+Click **Skip** if you want to skip automatic configuration and set it up manually later.
+
+## Build settings
 
-   ![select-branch.png](/img/_paligo/uuid-04948b79-fd8e-253c-85c5-3c0e66f9dbd9.png)
-1. Configure the project settings. You can either modify and confirm the automatically generated settings, or create a configuration manually.
+Review and adjust the build settings for your project:
 
-   The configuration sets [a stack](/en/bitrise-build-hub/infrastructure/build-stacks/about-build-stacks), [machine type](/en/bitrise-build-hub/infrastructure/build-machine-types), and a project root directory, among other things. The exact parameters to configure depends on the project type.
-1. Select a project icon. You can skip this and add an icon later.
+- **Build machine** and **Stack**: Bitrise pre-selects optimal settings based on your project type. You can change these later in the Workflow Editor. See [Build machine types](/en/bitrise-build-hub/infrastructure/build-machine-types) and [Build stacks](/en/bitrise-build-hub/infrastructure/build-stacks/about-build-stacks).
+- **Access to builds**: choose **Private** (only Workspace members can access build logs and the CI configuration file) or **Public** (anyone with the link can view them). See [Public projects](/en/bitrise-platform/projects/public-projects).
+- **Register webhooks**: enable this toggle to let Bitrise automatically register a webhook in your repository so builds trigger on code changes. Not needed if you use the GitHub App. See [Adding incoming webhooks](/en/bitrise-platform/integrations/webhooks/adding-incoming-webhooks).
 
-   ![app-icon.png](/img/_paligo/uuid-69955083-387a-53a2-2da4-ba67c85ef5bb.png)
-1. For apps with OAuth connections, add a [webhook](/en/bitrise-platform/integrations/webhooks/adding-incoming-webhooks). A webhook is required to [automatically trigger builds](/en/bitrise-ci/run-and-analyze-builds/build-triggers/configuring-build-triggers).
+![Build settings — machine, stack, access, and webhooks](/img/getting-started/2026-06-27-add-ci-config-build-settings.png)
 
-   Projects with the [GitHub App integration](/en/bitrise-platform/repository-access/github-app-integration) don't need a webhook.
-1. Once you are done, click **View Project Page** to go to the newly added project's home page. From there, you can start [editing your Workflows](/en/bitrise-ci/workflows-and-pipelines/workflows/workflows-overview) and [run builds](/en/bitrise-ci/run-and-analyze-builds/starting-builds/approving-pull-request-builds).
+Click **Finish**. Bitrise kicks off your first build and takes you to the build page where you can watch it run in real time. From there, you can start [editing your Workflows](/en/bitrise-ci/workflows-and-pipelines/workflows/workflows-overview) and [run builds](/en/bitrise-ci/run-and-analyze-builds/starting-builds/approving-pull-request-builds).
@@ -28,33 +28,21 @@ For more information about the trial and the paid subscription plans, check out
 
 ## Adding your first CI project
 
-Watch the walkthrough to get set up with your first CI project on Bitrise, or follow the step-by-step guide below.
-
-After signing up, select **Build, test and deploy my mobile or web project**.
-
-![new-getting-started-page.png](/img/_paligo/uuid-87e4d1a2-b6f1-9870-17b4-54d76e188eb8.png)
-
 :::note[First workspace]
 
 Bitrise automatically creates your first [workspace](/en/bitrise-platform/workspaces/workspaces-overview). You need at least one workspace to be able to add projects and run builds. Your subscriptions are also tied to your workspaces.
 
 :::
 
-Follow the instructions to add your project. During the process, you will:
+On the **Dashboard**, click **New project** and select **Configure Bitrise CI**. The **Add CI config** wizard walks you through three stages:
 
-1. [Configure repository access](/en/bitrise-platform/repository-access/repository-access-with-oauth).
+1. **Repository**: connect to your Git provider, select a repository, authorize Bitrise to access it, and select a default branch.
+1. **CI configuration**: Bitrise scans your repository and generates a starter configuration. If it can’t detect your project type automatically, select it manually from the **Project type** dropdown.
+1. **Build settings**: review the pre-selected build machine and stack, choose whether builds are private or public, and optionally register a webhook so builds trigger on code changes automatically.
 
-   :::note
-
-   For self-hosted GitLab or Bitbucket Server, use the dedicated menu option in the **Provider** dropdown menu. Do not paste the URL into **Other**.
-
-   :::
-1. Set up authentication, if necessary: [Configuring SSH keys](/en/bitrise-platform/repository-access/configuring-ssh-keys). We recommend using the GitHub app for authentication, however: [GitHub app integration](/en/bitrise-platform/repository-access/github-app-integration).
-1. Set up a default branch. Bitrise will build from this branch unless your configuration specifies a different one.
-1. Choose between manual configuration or automatic configuration. Automatic configuration means the <GlossTerm baseform="project scanner">project scanner</GlossTerm> scans your repository and identifies your project type. Based on the project type, a configuration is generated.
-1. [Register a webhook](/en/bitrise-platform/integrations/webhooks/adding-incoming-webhooks). Webhooks allow you to automatically <GlossTerm baseform="trigger">trigger</GlossTerm> builds.
+Click **Finish**. Bitrise kicks off your first build and takes you to the build page where you can watch it run in real time.
 
-After you’ve completed these steps, Bitrise will kick off your first build and you can watch it running in real time.
+For the full step-by-step guide, see [Adding a new project](/en/bitrise-ci/getting-started/adding-a-new-project).
 
 
 ## Changing your project settings

@@ -1,5 +1,5 @@
 {
-  "label": "Quick start guides",
+  "label": "Quickstart guides",
   "position": 7,
   "link": null
 }