Background Community-based health promotion (CBHP) programmes can yield sustainable and transformational changes to complex problems such as intergenerational transmission of social exclusion. However, investments in these projects are held back by lack of evidence on their effectiveness. The realist evaluation (RE) framework is regarded as a promising approach to improve understanding of how programmes generate their outcomes and the way they interact with their context. We look at two CBHP programmes to reflect on how RE can help relate their interventions to their outcomes. Methods We applied the RE approach to: “Football United” a sports for development programmes aiming to support refugee and newly arrived young people and families in their transition into Australian society and to, “Together, health for all in Pays de Redon –Bretagne Sud” a French programme to improve local capacities in addressing the social determinants of health in decision- and policy-making processes. Analyses were conducted on the basis of data collected through semi-structured interviews, documents, observations, etc. Results In both cases, application of the RE perspective highlighted difficulties in identifying the context-mechanism-outcomes configurations that are at the core of the approach. We clarified the definition of mechanism that was initially repeatedly confused with that of intervention/activity. Whereas both programme theories were quite straightforward, they required a whole array of activities critical in shaping the conditions for the implementation of the interventions. Conclusions Our results echo other critics of the conceptual apparatus of the RE approach. While the RE has proven promising in linking CBHP interventions to their outcomes, practitioners still need better tools to grasp the complexity and the dynamic of changes brought on complex systems of actors. Key messages: CBHP programmes can yield sustainable transformational change to complex situations but current evaluation approaches often fail to bring evidence on their effectiveness For the sake of knowledge transfer, theory-based evaluation approaches such as RE also need to capture the broad array of supporting activities of CBHP programmes