Newcomer question: what are builds, jobs and stages?

I got some basics question about CI and need some clarification.
I have an issue in github. Please help.

And is there any document for new, especially the basic concepts. The official doc is not full.

What I am confused of are build and stage. ? I find the stage in some file, but I can not understand what is the build? From the description, I can not figure it out.

Using as an example:

  • A build is what the entire main panel of that page represents
  • Jobs are individual lines in the list under “build jobs”
  • Stages are groups of jobs that would run only after the previous stage completes. In that build, there are two stages – “test” (the default stage) and “ship it to”, run in that order.
    • Stages are optional. By default, all jobs run in parallel, subject only to Travis-imposed resource limits (from my experience, 3-5 Linux jobs and 2-3 OSX jobs from the same build run at a time).
    • In that build, the stage mechanic ensures that the “ship” job would only run after all 3 test jobs complete (and if any of them fails, it wouldn’t run at all).

Stages are a bit clunky because they are a late addition to the system and were stamped on top of existing mechanics.

In particular, matrix expansion knows nothing about stages and only adds jobs to the default stage (and the stages: clause is not considered an axis unlike most other top-level clauses). Any jobs that would go into other stages have to be specified manually one by one, via matrix: include:.

Earlier stages can pass their resulting artifacts to later stages via Travis cache, but only in a very limited fashion: jobs from different stages have to have exactly the same configuration (except the stage name and scripts) – then they will share the same cache location.

  • In the example, the “ship” job with a blank env: will share a cache with an explicitly added “test” job with a blank env:. If you check their logs, you will see that the “test” job saves its results to the Travis cache and the “ship” job restores the same cache.

Thanks very much for this explanation. It is very helpful.

One more question:
What is difference between the same phases in and out the jobs?
Like I have a before_script and a script in one of my stage, and I get all of declaration out the stage too.
How do they run? There is not interference among them or they overwrite each other.

Is there any detailed doc for this stuff?

before_* and after_* phases run, as the names suggest, immediately before and after the corresponding build phase.

Sometimes, it’s more convenient to insert some commands there rather than into the corresponding phase itself (and for some build phases, it’s not even possible to directly define the phase’s logic, only indirectly).

Sometimes, it’s more convenient to insert some commands there rather than into the corresponding phase itself

Does this mean we can insert this before_* and after_* out of the job? And they will be executed in every jobs?

These clauses are treated the same as other job phase clauses. So, yes, if you specify them at top level, they should propagate to all jobs unless overridden.

(I can’t 100% guarantee that though, there might be some shenanigans in some corner cases. travis.yml logic isn’t the most straightforward one.)

You can suggest an improvement to documentation using the “Improve this page on Github” link which exists on top of every docmentation page (e.g. for the “Build Stages” page, it leads to

Your vision of an improvement will be more useful than mine because you know exactly what a novice wants the documentation page to tell about.

As tested, the env out of the stage, will override the env inside of stage.
I think other components got the same situation here.

Please link to your test – because my test suggests otherwise.

The test is internal. I did not include global just env. So when the env is out of stage, global must be included?