1(pipelines)= 2 3# GitLab CI Pipelines 4 5PETSc uses [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/) for testing during continuous integration. 6 7Do not overdo requesting testing; it is a limited resource, so if you 8realize a currently running pipeline is no longer needed, cancel it. 9 10The pipeline status for a merge request (MR) is displayed near the top of the MR page and in the pipelines tab. 11 12(The figures below are high resolution, so zoom in if needed) 13 14:::{figure} /images/developers/pipeline-from-MR.png 15:align: center 16:width: 90% 17 18Pipeline status for a merge request (MR) 19::: 20 21To un-pause the pipeline, click the "play" button (or start a new one with "Run Pipeline" if necessary). 22 23:::{figure} /images/developers/run-paused-pipeline.png 24:align: center 25:width: 90% 26 27Un-pausing a pipeline. 28::: 29 30A pipeline consists of "Stages" each with multiple "Jobs". Every job is one configuration on one machine. 31 32:::{figure} /images/developers/show-failure.png 33:align: center 34:width: 90% 35 36Examining a failed pipeline stage. 37::: 38 39You can see the failed jobs by clicking on the X. 40 41:::{figure} /images/developers/find-exact-bad-job.png 42:align: center 43:width: 90% 44 45Locating the exact failed job in a pipeline stage. 46::: 47 48A job is a run of the {any}`PETSc test harness<test_harness>` and consists of many "examples". 49Each test is a run of an example with a particular set of command line options 50 51A failure in running the job's tests will have `FAILED` and a list of the failed tests 52 53:::{figure} /images/developers/failed-examples.png 54:align: center 55:width: 90% 56 57Failed examples in a pipeline job. 58::: 59 60Search for `not ok` in the jobs output to find the exact failure 61 62:::{figure} /images/developers/unfreed-memory.png 63:align: center 64:width: 90% 65 66A test that failed because of unfreed memory. 67::: 68 69After you have fixed a problem that appeared in a particular (set of) job(s) you may want to test your fix only on those jobs. To do this use 70 71```console 72$ ./lib/petsc/bin/maint/runjobs.py [job_1 job_2 ... job_N] 73``` 74 75where `job_1` is, for example, `linux-intel`. The script will then prompt you to push the branch of the MR, once pushed the listed jobs will automatically be run 76without you needing to access the GitLab website to un-pause the pipeline. 77 78(more_test_failures)= 79 80## Examples of pipeline failures 81 82If your source code is not properly formatted you will see an error from `make checkbadSource`. Always run `make checkbadSource` on your machine 83before submitting a pipeline. 84 85:::{figure} /images/developers/badsource.png 86:align: center 87:width: 90% 88 89`checkbadSource` failure. 90::: 91 92:::{figure} /images/developers/another-failure.png 93:align: center 94:width: 90% 95 96A test failing with a PETSc error. 97::: 98 99:::{figure} /images/developers/error-compiling-source.png 100:align: center 101:width: 90% 102 103Error in compiling the source code. 104::: 105 106You can download the `configure.log` file to find the problem using the "Browse" button and following the paths to the configure file. 107 108:::{figure} /images/developers/pipeline-configure.png 109:align: center 110:width: 90% 111 112Error in running configure. 113::: 114 115:::{figure} /images/developers/pipeline-configure-browse.png 116:align: center 117:width: 90% 118 119Downloading `configure.log` from a failed pipeline job. 120::: 121 122The "Retry" button at the top of a previous pipeline or job does **not** use any 123new changes to the branch you have pushed since that pipeline was started - it retries the 124same Git commit that was previously tried. The job "Retry" should only be used this way 125when you suspect the testing system has some intermittent error unrelated to your branch. 126 127Please report all "odd" errors in the testing that don’t seem related 128to your branch in the PETSc Discord channel `testing-ci-forum`. 129 130Check the forum's threads to see if the error is listed and add it there, with a link to your MR (e.g. `!1234`). Otherwise, create a new thread. 131
