Overview / Quick Answer

When setting up a new project, CircleCI initially only builds your default branch (usually main or master). Other branches will appear in the CircleCI dashboard only after you push a commit to them that includes a valid .circleci/config.yml file.

Why This Happens

CircleCI uses a trigger-based approach for discovering branches:

When you first connect a repository, CircleCI automatically sets up a webhook to monitor your default branch
Other branches are discovered only when new commits are pushed to them
This prevents CircleCI from building potentially outdated or experimental branches without your explicit intent

Solutions

Option 1: Push a New Commit (Recommended)

The simplest way to get a branch to appear in CircleCI:

Switch to your desired branch locally
Make any small change (even just updating a comment)
Commit and push the change
CircleCI will detect the branch and attempt to build it

Example:

git checkout feature-branch
git commit --allow-empty -m "Trigger CircleCI build"
git push origin feature-branch

Option 2: Ensure Config File Exists

If pushing a commit doesn't work, verify your branch has the required configuration:

Check that .circleci/config.yml exists in your branch
Ensure the config file is valid YAML
Make sure the config file is in the root .circleci/ directory (not nested deeper)

Option 3: Re-push Existing Commits

If you don't want to create new commits:

git checkout feature-branch
git push origin feature-branch --force-with-lease

⚠️ Warning: Use --force-with-lease carefully in shared repositories.

Troubleshooting

Branch Still Not Appearing?

Check these common issues:

Missing or Invalid Config File
- Ensure .circleci/config.yml exists in your branch
- Validate your YAML syntax using a YAML validator
- Check that you're using CircleCI 2.0+ syntax
Webhook Issues
- Go to your repository settings and verify the CircleCI webhook is active
- Try disconnecting and reconnecting your project in CircleCI
Permission Problems
- Ensure CircleCI has proper access to your repository
- Check that your VCS (GitHub/Bitbucket) permissions allow CircleCI to read all branches
Branch Protection Rules
- Some repository protection rules might prevent CircleCI from accessing certain branches
- Review your repository's branch protection settings

Still Having Issues?

Check the Activity Feed: Look in your CircleCI project's Activity tab for any error messages
Review Webhooks: In your repository settings, check if webhooks are being delivered successfully

Test with a Simple Config: Try pushing a minimal .circleci/config.yml to isolate configuration issues:

version: 2.1
jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - run: echo "Hellow World"
workflows:
  version: 2
  build:
    jobs:
      - build

Understanding CircleCI Branch Discovery

How it works:

CircleCI monitors your repository via webhooks
When you push to a branch, the webhook triggers CircleCI to evaluate that branch
If a valid config file is found, the branch becomes "active" and appears in your dashboard
Branches without recent commits or valid configs remain hidden to reduce clutter

Best practices:

Keep your .circleci/config.yml in your default branch and merge it to feature branches
Use dynamic configuration for complex branching strategies
Consider using path filtering to optimize builds