Add cross-repo CI: trigger downstream tests on PR success

[dannyroberts]

Technical Summary

Adds automated cross-repo CI: when a commcare-core PR passes its own tests, the
test suites of commcare-android and formplayer are automatically triggered against
the PR's version of commcare-core. Results are reported back as commit statuses on
the commcare-core PR.

Design:

• A new trigger-downstream.yml workflow fires via workflow_run after
  CommCare Core Build succeeds on a PR
• Sets pending commit statuses, then fires workflow_dispatch to both downstream
  repos and exits (fire-and-forget)
• Downstream workflows report success/failure back via the GitHub commit status API
• A dedicated GitHub App ("CommCare Cross-Repo CI") handles cross-repo
  authentication, installed with minimal permissions (Actions write, Commit
  statuses write) on all three repos

Cross-request PRs:

• commcare-android: Add cross-repo CI support for commcare-core PRs commcare-android#3623
• formplayer: Add cross-repo CI support for commcare-core PRs formplayer#1764

Note: the final commit on this branch temporarily targets the dmr/cross-repo-ci
branch on downstream repos for Stage 2 end-to-end testing. Once those PRs are
merged, it will be updated to target master.

Safety Assurance

Safety story

This change only adds a new workflow — no existing code or workflows are modified.
The new workflow runs after a successful build and exits immediately after
dispatching; it cannot cause a previously-passing build to fail.

End-to-end tested in two stages:

1. Downstream workflows manually dispatched on feature branches — verified correct
   SHA checkout and status callbacks on a commcare-core test PR
2. Full trigger chain tested via this PR (in progress)

Automated test coverage

No automated tests — this is CI infrastructure. Validated by manual end-to-end
testing.

QA Plan

Verified via live GitHub Actions runs: pending statuses appear on the PR, downstream
workflows run against the correct commcare-core SHA, and status callbacks update the
PR correctly.

Special deploy instructions

• This PR can be deployed after merge with no further considerations.

Rollback instructions

• This PR can be reverted after deploy with no further considerations.

Review

• The set of people pinged as reviewers is appropriate for the level of risk of the change.

Summary by CodeRabbit

• Chores
  • Established automated cross-repository testing infrastructure that triggers validation of downstream mobile and server components when core changes are submitted via pull request. Tests execute automatically across the ecosystem and report results back, streamlining quality assurance and reducing manual verification overhead.

[coderabbitai]

Walkthrough

This PR introduces a cross-repository CI system for commcare-core that automatically triggers downstream test runs in commcare-android and formplayer repositories upon successful builds. It adds a trigger-downstream GitHub Actions workflow, comprehensive implementation plans, and design specifications for GitHub App-based authentication and status reporting.

Changes

Cohort / File(s)	Summary
Workflow Implementation .github/workflows/trigger-downstream.yml	New GitHub Actions workflow that listens for successful "CommCare Core Build" completions, generates GitHub App tokens, extracts PR metadata, sets pending commit statuses, and dispatches downstream workflows to commcare-android and formplayer with cross-repo context (SHA, PR number, check name). Includes error handling with status rollback on dispatch failures.
Documentation docs/superpowers/plans/2026-03-17-cross-repo-ci.md, docs/superpowers/specs/2026-03-17-cross-repo-ci-design.md	Comprehensive cross-repo CI architecture documentation defining the fire-and-forget workflow pattern, GitHub App authentication setup, downstream workflow modifications (workflow_dispatch triggers, submodule overrides, status reporting), staged testing plan, and operational flows including branch protection deferral and known limitations.

Sequence Diagram

sequenceDiagram
    actor CCCore as CommCare Core<br/>Build
    participant TriggerDown as trigger-downstream<br/>Workflow
    participant GHApp as GitHub API<br/>(App Auth)
    participant Android as commcare-android<br/>Workflow
    participant Formplayer as formplayer<br/>Workflow
    
    CCCore->>TriggerDown: workflow_run event<br/>(on success)
    TriggerDown->>GHApp: Generate App Token
    TriggerDown->>GHApp: Extract PR Info &<br/>Set Pending Status
    
    par Dispatch Downstream
        TriggerDown->>Android: createWorkflowDispatch<br/>(inputs: SHA, PR, check_name)
        TriggerDown->>Formplayer: createWorkflowDispatch<br/>(inputs: SHA, PR, check_name)
    end
    
    par Run Downstream Tests
        Android->>Android: Checkout commcare-core<br/>at provided SHA
        Android->>Android: Run Tests
        Android->>GHApp: Post Status Back<br/>to commcare-core PR
        
        Formplayer->>Formplayer: Override submodule<br/>Checkout commcare-core
        Formplayer->>Formplayer: Run Tests
        Formplayer->>GHApp: Post Status Back<br/>to commcare-core PR
    end
    
    alt On Error
        TriggerDown->>GHApp: Set Error Status<br/>on commcare-core PR
    end

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A workflow so clever, it hops through the repos,
Triggering tests where the commcare code flows,
Android and Formplayer dance to the tune,
While statuses bloom like spring flowers in June! 🌸
Cross-repo CI magic, automated and bright,
The rabbit approves—this refactor's just right! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a GitHub Actions workflow that triggers downstream tests when a PR succeeds, which aligns directly with the primary objective of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• ❌ Create stacked PR
• ❌ Commit on current branch

🧪 Generate unit tests (beta)

• ❌ Create PR with unit tests
• ❌ Commit unit tests in branch dmr/cross-repo-ci

📝 Coding Plan

• ❌ Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/trigger-downstream.yml:
- Line 77: The workflow currently hardcodes the downstream Git ref with "ref:
'dmr/cross-repo-ci'"; change this so dispatches target the intended production
branch instead of a test branch by replacing the literal with a dynamic value
(e.g., use an input or environment variable like inputs.ref or
env.DOWNSTREAM_REF, or derive from GitHub context such as
github.event.repository.default_branch or github.ref_name) in the step that sets
ref; update the job that uses the ref key to read that variable (symbol: ref) so
merges/dispatches point to the correct branch rather than the fixed
dmr/cross-repo-ci string.
- Around line 11-14: The workflow if-condition is missing a base-branch guard
and can trigger downstream dispatch for PRs targeting other branches (e.g.,
formplayer); update the if expression that uses
github.event.workflow_run.conclusion, github.event.workflow_run.event and
github.event.workflow_run.pull_requests[0] to also check the PR base ref (e.g.,
github.event.workflow_run.pull_requests[0].base.ref == 'master') so the dispatch
only runs for PRs targeting the intended branch.

In `@docs/superpowers/plans/2026-03-17-cross-repo-ci.md`:
- Around line 72-79: The YAML example uses ref: 'master' but the staged-testing
workflow in this PR uses ref: 'dmr/cross-repo-ci'; update the plan text around
the "Trigger Downstream Tests" snippet and the duplicate snippet at lines
referenced to add a clear temporary override note instructing operators to use
ref: 'dmr/cross-repo-ci' (or set the ref to match the staged-testing branch)
when running the example, so include an explicit sentence like "Temporary: when
following this plan for staged testing in this PR, override ref: 'master' with
ref: 'dmr/cross-repo-ci' to match the current staged-testing branch." Ensure
both the snippet near the workflow_run example and the other occurrence (the
duplicate at the later snippet) are updated.

In `@docs/superpowers/specs/2026-03-17-cross-repo-ci-design.md`:
- Around line 27-29: Add an explicit temporary-note explaining that the workflow
dispatch targets the non-default branch dmr/cross-repo-ci (not the downstream
default branch) so readers aren’t misled by the lines "Triggers
workflow_dispatch on commcare-android (default branch)" and "Triggers
workflow_dispatch on formplayer (default branch)"; update both occurrences (the
block around those lines and the later mention) to include a short
temporary-note block stating the override branch name, why it’s used, and when
it will be removed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2de6faee-0f99-4c53-98fc-4b94b375ed38

📥 Commits

Reviewing files that changed from the base of the PR and between 25fc5ef and 61aa3cc.

📒 Files selected for processing (3)

• .github/workflows/trigger-downstream.yml
• docs/superpowers/plans/2026-03-17-cross-repo-ci.md
• docs/superpowers/specs/2026-03-17-cross-repo-ci-design.md