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:

1. Switch to your desired branch locally
2. Make any small change (even just updating a comment)
3. Commit and push the change
4. 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:

1. Check that .circleci/config.yml exists in your branch
2. Ensure the config file is valid YAML
3. 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:

1. 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
2. Webhook Issues
   • Go to your repository settings and verify the CircleCI webhook is active
   • Try disconnecting and reconnecting your project in CircleCI
3. Permission Problems
   • Ensure CircleCI has proper access to your repository
   • Check that your VCS (GitHub/Bitbucket) permissions allow CircleCI to read all branches
4. Branch Protection Rules
   • Some repository protection rules might prevent CircleCI from accessing certain branches
   • Review your repository's branch protection settings

Still Having Issues?

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

3. 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

Additional Resources

• CircleCI Configuration Reference
• Setting Up Your Build
• Dynamic Configuration