Create and synchronize a PR in a dependent repository ## Description When used in a workflow triggered by a PR event, it will create, update and close a matching PR in another repository. Whenever the matching PR is modified by `cascading-pr`, it waits for the CI to pass otherwise it fails. As an example, when a PR is created in [`forgejo/runner`](https://code.forgejo.org/forgejo/runner/), a matching PR is created in [`actions/setup-forgejo`](https://code.forgejo.org/actions/setup-forgejo/) with the proposed change. `cascading-pr` will wait until the CI in `actions/setup-forgejo` is successful. When the PR in `forgejo/runner` is merged, the matching PR in `actions/setup-forgejo` is updated to use what was just merged and is ready to be reviewed. The `update` script is expected to be found in the checked out repository running the PR. It is given three arguments: * A directory in which the destination repository is checked-out * A file with the JSON describing the pull request in the destination repository * A file with the JSON describing the pull request in the origin repository If changes are found in the destination repository directory, they will be pushed as a new commit in the PR. ## Inputs | parameter | description | required | default | | --- | --- | --- | --- | | origin-url | URL of the Forgejo instance where the PR that triggers the action is located (e.g. https://code.forgejo.org) | `true` | | | origin-repo | the repository in which the PR was created | `true` | | | origin-token | a token with write permission on origin-repo | `true` | | | origin-pr | number of the PR in {orign-repo} | `true` | | | destination-url | URL of the Forgejo instance where the cascading PR is created or updated (e.g. https://code.forgejo.org) | `true` | | | destination-repo | the repository in which the cascading PR is created or updated | `true` | | | destination-branch | the base branch of the destination repository for the cascading PR | `true` | | | destination-token | a token with write permission on destination-repo | `true` | | | update | path to the script to update the content of the cascading PR | `true` | | | prefix | prefix of the cascading PR created on destination-repo (default to {origin-repo}) | `false` | | | verbose | if true print verbose information | `false` | false | | debug | if true print debug information | `false` | false | # Example ```yaml on: pull_request: types: - opened - synchronize - closed jobs: test: runs-on: docker steps: - uses: actions/checkout@v4 - uses: actions/cascading-pr@v1 with: origin-url: https://code.forgejo.org origin-repo: forgejo/lxc-helpers origin-token: ${{ secrets.ORIGIN_TOKEN }} origin-pr: ${{ github.event.pull_request.number }} destination-url: https://code.forgejo.org destination-repo: forgejo/actd destination-branch: main destination-token: ${{ secrets.DESTINATION_TOKEN }} update: ./upgrade-lxc-helpers ``` # Hacking The test environment consists of the following (all users password is admin1234) * A forgejo instance with a runner * An unprivileged user user1 * The repository user1/originrepo * contains a pull_request workflow using cascading-pr that targets user2/destinationrepo * contains a script that will modify user2/destinationrepo * a branch1 at the same commit as main * The repository user1/cascading-pr with the action under test * An unprivileged user user2 * The repository user2/destinationrepo ```sh git clone https://code.forgejo.org/actions/setup-forgejo export PATH=$(pwd)/setup-forgejo:$PATH git clone https://code.forgejo.org/actions/cascading-pr cd cascading-pr forgejo-curl.sh logout forgejo-runner.sh teardown forgejo.sh teardown forgejo.sh setup root admin1234 codeberg.org/forgejo/forgejo 1.21 FORGEJO_RUNNER_CONFIG=$(pwd)/tests/runner-config.yaml forgejo-runner.sh setup url=http://$(cat forgejo-ip):3000 firefox $url ``` The test for a successful run of the cascading-pr action consists of: * creating a PR from branch1 to main * wait for the commit status until it is successful ## testing an update on the action * run `tests/run.sh --debug` once so all is in place * commit changes to the files that are in the cascading-pr action (action.yml, cascading-pr.sh etc.) * push the modified action to `user1/cascading-pr` * visit $url/user1/originrepo/actions/runs/1 and click re-run ## interactive debugging Following the steps below recreate the same environment as the integration workflow locally. It is helpful for forensic analysis when something does not run as expected and the error displayed are unclear. To help with the development loop all steps are idempotent and running `tests/run.sh --debug` multiple times must succeed. Individual steps can be run independendely by using the name of the function. For instance: * `tests/run.sh --debug create_pull_request` will only call the `create_pull_request` function found in `tests/run.sh` to (re)create the pull request in `user1/originrepo`. * `./cascading-pr.sh --debug --origin-url ... upsert_branch` will only call the `upsert_branch` function found in `cascading-pr.sh`. ## directories The `tests/run.sh` script stores all its files in `/tmp/cascading-pr-test`. The temporary directories created by `cascading-pr.sh` are disposed of when the script ends. ## logging If `--debug` is used a full debug log is displayed, very complete and very verbose. Otherwise it is stashed in a temporary file and only displayed if an error happens. ## snippets for copy/pasting ```sh git clone https://code.forgejo.org/actions/setup-forgejo export PATH=$(pwd)/setup-forgejo:$PATH git clone https://code.forgejo.org/actions/cascading-pr cd cascading-pr forgejo-curl.sh logout forgejo-runner.sh teardown forgejo.sh teardown forgejo.sh setup root admin1234 codeberg.org/forgejo/forgejo 1.21 FORGEJO_RUNNER_CONFIG=$(pwd)/tests/runner-config.yaml forgejo-runner.sh setup url=http://$(cat forgejo-ip):3000 firefox $url tests/run.sh --debug tests/run.sh --debug create_pull_request ./cascading-pr.sh --debug --origin-url "$url" --origin-repo "user1/originrepo" --origin-token "$(cat /tmp/cascading-pr-test/user1/repo-token)" --origin-pr 1 --destination-url "$url" --destination-repo "user2/destinationrepo" --destination-token "$(cat /tmp/cascading-pr-test/user2/repo-token)" --destination-branch "main" --update "upgraded" run ``` ## Update the README With https://github.com/npalm/action-docs `action-docs --update-readme`