index.lit

\title{Concourse}{index}

\use-plugin{concourse-docs}
\styled{index}

\splash-intro{
  \inline-header{Concourse is an open-source continuous thing-doer.}

  Centered around the simple mechanics of \reference{resources}{resources},
  \reference{tasks}{tasks}, and \reference{jobs}{jobs}, Concourse delivers a
  versatile approach to automation that excels at
  \link{CI}{https://en.wikipedia.org/wiki/Continuous_integration}/\link{CD}{https://en.wikipedia.org/wiki/Continuous_delivery}.

  \button{\reference{quick-start}}
}{
  \download-links
}

\page-region{light}{Core features}{
  Concourse is engineered to be \link{expressive, versatile, and
  secure}{https://github.com/concourse/rfcs/blob/master/DESIGN_PRINCIPLES.md},
  remaining intuitive even as your project complexity grows.

  \side-by-side{
    \inline-header{Code-based configuration}

    \codeblock{yaml}{{{
    resources:
    - name: booklit
      type: git
      source: {uri: "https://github.com/concourse/booklit"}

    jobs:
    - name: unit
      plan:
      - get: booklit
        trigger: true
      - task: test
        file: booklit/ci/test.yml
    }}}
  }{
    \inline-header{Visual verification}

    \include-template{basic-pipeline-svg}
  }

  \side-by-side{
    A Concourse \reference{pipelines}{pipeline} functions like a distributed, continuous
    \code{Makefile}.

    Each \reference{jobs}{job} contains a \reference{schema.job.plan}{build plan}
    defining the job's input \reference{resources}{resources} and what actions to perform
    with them when changes occur.
  }{
    Your pipeline appears visualized in the web UI, requiring just one click to move
    from a failed job to understanding the cause of failure.

    The visualization provides immediate feedback: if it \italic{looks}
    wrong, it probably \italic{is} wrong.
  }

  \inline-header{A more complex example...}

  Jobs can depend on other jobs through \reference{schema.get.passed}{\code{passed}} constraints.
  The resulting network of jobs and resources creates a dependency graph that continuously
  advances your project forward, from source code to production.

  \include-template{pipeline-image}

  \italic{This pipeline example can be found in the \link{Booklit
  repository}{https://github.com/concourse/booklit/blob/8741a4ca3116dcf24c30fedfa78e4aadcaff178a/ci/pipeline.yml}.}

  \splash-example{Source-controlled CI}{
    All configuration and management happens through \reference{fly-cli}{the
    \code{fly} CLI}.

    The \reference{fly-set-pipeline} command uploads your configuration to Concourse.
    Once finalized, you can commit the file to source control, making it easy to
    recover your project if you migrate to a new Concourse server.
  }{
    \codeblock{sh}{{{
    $ fly -t ci set-pipeline -p booklit -c pipeline.yml
    $ vim pipeline.yml
    $ fly -t ci set-pipeline -p booklit -c pipeline.yml
    $ git add pipeline.yml
    $ git commit -m "initial pipeline"█
    }}}
  }

  \splash-example{Reproducible, debuggable builds}{
    Everything executes in containers, ensuring a clean environment for each run.

    Every \reference{tasks}{task} specifies its own image, providing complete control
    over its dependencies, instead of managing packages on your workers.

    The \reference{fly-intercept} command lets you access a build's containers directly,
    simplifying troubleshooting of problematic builds.
  }{
    \codeblock{sh}{{{
    $ fly -t ci intercept -j booklit/unit -s unit
    root@2c15ff11:/tmp/build/0df9eea0# ps
        PID TTY          TIME CMD
        171 pts/1    00:00:00 bash
       1876 pts/1    00:00:00 ps
    root@2c15ff11:/tmp/build/0df9eea0# ls
    depspath  gopath
    root@2c15ff11:/tmp/build/0df9eea0# █
    }}}
  }

  \splash-example{Efficient local testing}{
    The \reference{fly-execute} command enables you to run builds with local modifications.

    These builds execute exactly as they would in your pipeline, eliminating the
    need to push incomplete commits while debugging.

    When a pipeline build fails, you can use \reference{fly-execute} with
    the \code{-j} flag to run a one-off build with the same inputs as the failed
    build. You can then replace an input with your local changes using \code{-i}
    to test your fix.
  }{
    \codeblock{sh}{{{
    ~/booklit $ fly -t ci execute -c ci/test.yml
    executing build 1 at http://localhost:8080/builds/1
    initializing
    booklit: 4.74 MiB/s 0s
    running gopath/src/github.com/concourse/booklit/ci/test
    fetching dependencies...
    installing ginkgo...
    running tests...
    █
    }}}
  }

  \inline-header{Custom integrations}

  \side-by-side{
    \codeblock{yaml}{{{
    resource_types:
    - name: rubygem
      type: registry-image
      source:
        repository: troykinsella/concourse-rubygems-resource

    resources:
    - name: rspec-gem
      type: rubygem
      source: {gem: rspec}

    jobs:
    - name: bundle
      plan:
      - get: rspec-gem
        trigger: true
      - # ...
    }}}
  }{
    Concourse doesn't rely on a complex plugin system. Instead, it focuses on a
    single powerful abstraction: \reference{resources}{resource}, which are
    implemented by \reference{resource-types}{resource types}.

    The \reference{schema.pipeline.resources} field configures external artifacts
    that your pipeline will monitor for changes, retrieve, and update.

    For instance, a resource with type \code{git} refers to a git repository,
    which will be \code{clone}d in a \reference{get-step} and \code{push}ed to
    using a \reference{put-step}. Behind the scenes, Concourse continuously
    runs \code{git fetch} to check for new commits that jobs might want to trigger
    on.

    At its foundation, Concourse has no built-in knowledge of \code{git}. It includes a
    \link{\code{git} resource type}{https://github.com/concourse/git-resource}
    by default, but you can easily integrate your own into your pipeline through
    the \reference{schema.pipeline.resource_types} field.

    To discover available resource types, check out the \link{Resource Types
    catalog}{https://resource-types.concourse-ci.org}!
  }
}

\split-sections

\include-section{./docs.lit}
\include-section{./examples.lit}
\include-section{./project.lit}
\include-section{./ecosystem.lit}