This page discusses how to resolve failures in the Github Actions of a Pull Request (PR).

Identifying which Github Action failed

Situation: You made a Pull Request to one of the protected branches (eg, master, dev, new_pipeline) and after waiting a bit, you see that something has failed in the Github Actions checks, as indicated by the red X.

1. Click on the PR and navigate to the area that says that there are failing checks. Select "details."

2. You will now see a screen similar to below. You should review the blocks that failed. If there isn't enough context provided in the window, you can click on the gear in the top right to "View raw logs" for a full text file of the log. This will help you identify where the error is.

3. If the error appears to be a failing taxdat unit test, you may see something like below under the "Run taxdat tests" section of the Github Actions. You should then identify which test(s) failed and review the code in packages/taxdat/tests/testthat to revise the unit test or identify which part of the pipeline code is not working as expected. You may see a similar image under the "Run integration tests" section if there is a failure in the integration test, which is a full pipeline model run for Kenya. To revise the integration test or identify which part of the pipeline code is not working as expected, you may desire to review the code in test/.

4. One reason that an integration test may fail is that a new R package is required to run the pipeline code. Before adding new R package requirements, the code contributor should consider whether it is absolutely necessary to use a function in this package or not. It is preferred to use functions in existing R packages if possible. If it is determined that loading this package is absolutely necessary, the R package will need to be added to the Docker image by performing actions on the update_docker branch. This is a special branch. When changes are pushed to this branch, Github Actions will deploy a new Docker image to hopkinsidd/choleramappingpipeline Dockerhub. The latest dev image on our Dockerhub will then be used in future Github Action checks to this repository. See more below.

Resolving failed unit tests

Review the code in packages/taxdat/tests

The Dockerfiles

To make the image build process less time-consuming, we have divided it into two stages. The first stage builds an image containing the required packages for the pipeline. The second stage sets up a PostgreSQL database for images used in integration tests.

Dockerfile_github_base

This Dockerfile contains the required R packages for the pipeline. If we need to add new packages, we should update this file. We prefer to use Conda to manage the packages.

Dockerfile_github_psql17

This Dockerfile is used to set up PostgreSQL 17 and create the necessary folders for runtime. If we need to change the version of PostgreSQL or PostGIS, this is the file to modify. All database-related operations for the container are handled by the shell script init-postures.sh.

Dockerfile_github_psql17_local

This Dockerfile is used for testing the final image configuration. It is almost identical to Dockerfile_github_psql17, except it copies the pipeline's code from the local machine instead of pulling it from GitHub. We use this file to test the built image and check for any missing required packages or issues with the integration tests.

Adding an R package to the Docker image

1. If it is deemed absolutely necessary to add an R package to the Docker image, we will need to update the Dockerfile Dockerfile_github_base. we can install it with conda or R commands, which depend on our needs.
2. Then we should rebuild the Docker image locally and test it. For testing, we need to confirm that the new container created with the updated docker file should be able to run unit tests and integration tests.
3. If everything works, then we need to push the new image file to Docker Hub and the Dockerfile changes to Github.

Adding an R package to the Docker image(All material from this section should be removed.)

If it is deemed absolutely necessary to add an R package to the Docker image, we will need to make changes to the update_docker branch. The below descriptions assume that dev is the primary production branch. For additional reference, consult the Dropbox training video "cholera_mapping_training_recordings/2022-10-05 Standardizing Runs and Using Docker" starting minute 57.

1. Install Docker on your local machine. Mac users may need to change some of the default memory settings in Docker Desktop (See more here.)
2. Merge dev into update_docker branch.
3. Checkout and pull update_docker.
4. Pull the latest-dev image from Dockerhub.

docker pull hopkinsidd/choleramappingpipeline:latest-dev

You should see a message that your image is up-to-date or a set of progress bars that show your computer pulling an updated image from Dockerhub. 5. Run the docker image mounted onto the cholera-mapping-pipeline repository in your Terminal. Windows and Linux users should be able to run the command as follows:

docker run -it -v <full-path-to-repository>/cholera-mapping-pipeline:/home/app/cmp hopkinsidd/choleramappingpipeline:latest-dev

Mac users with an Apple silicon chip should use the following command to ensure cross-platform compatibility:

docker run --platform=linux/amd64 -it -v <full-path-to-repository>/cholera-mapping-pipeline:/home/app/cmp hopkinsidd/choleramappingpipeline:latest-dev

Assuming this was successful, your Terminal commands will now be executed inside the Docker. 6. Now, you want to install the new R package(s) in R in the Docker. In the Terminal, open R. While in R, execute:

renv::install("my-new-package")
## the package installs successfully!
renv::snapshot(packages = rownames(installed.packages()))
## R will ask you if you want to update "my-new-package" in the Renv.lock file. Say "Yes"

7. Exit R in Docker. We should now review the files in the Docker home directory (not the cholera-mapping-pipeline repository directory) for evidence that your new packages were installed. It is good practice to diff the files that were expected to change. For example:

diff renv.lock cmp/renv.lock
diff .Rprofile cmp/Docker.Rprofile
diff -r renv cmp/renv
diff -r .cache cmp/renv.cache

In the above lines, the first file or folder listed (e.g., renv.lock) is the object that may have been updated when you installed the new R package. The second file or folder listed (e.g., cmp/renv.lock) should be the comparable object that exists in the current Docker image.

8. Once you confirm that the expected changes were made, we now need to copy the updated objects from the Docker home directory to the cholera-mapping-pipeline repository directory. The reason is as follows: when changes are pushed to the update_docker repository, we have a Github Action that deploys the files from the repository to Dockerhub and updates the Docker image therein. Thus, we need to copy the files that were created in the Docker home directory to our GH repository in order to ensure that the updated files get pushed into our new Docker build.

To copy the files, you may execute:

cp renv.lock cmp/renv.lock
cp .Rprofile cmp/Docker.Rprofile
cp -r renv/. cmp/renv/
## note that copying the cache make take a long time
cp -r .cache/. cmp/renv.cache/

9. Now exit the Docker with the command exit. You are back in your local computer's Terminal.

10. Make sure you have git lfs installed, as you may be required to commit large files to the repository. Then you will add all of the new files and folders to the repository.

## if you don't already have lfs installed
git lfs install 
## note that adding the cache may take a long time
git add renv.lock renv.cache/ renv/ Docker.Rprofile 
git commit
git push

11. Go to the cholera-mapping-repository on the Github website. Under Actions you should see a new process running on update_docker branch. If this process completes successfully, you should be able to see that a new Docker image was built and pushed to Dockerhub here.