diff --git a/docs/core-concepts/1202-plan.md b/docs/core-concepts/1202-plan.md index 2e15322e..8e22fc7a 100644 --- a/docs/core-concepts/1202-plan.md +++ b/docs/core-concepts/1202-plan.md @@ -4,3 +4,76 @@ displayed_sidebar: europa --- # It all starts with a plan + +A CI/CD pipeline declared in Dagger starts with a plan, specifically `dagger.#Plan` + +This plan is the entrypoint for everything that runs within a pipeline. + +The simplest plan will have at least one input - the source code - and a few actions, usually build, test & deploy. +This is our **Getting Started** example app plan structure: + +```cue +dagger.#Plan & { + inputs: { + directories: app: path: "./" + // ... + } + actions: { + build: yarn.#Build & { + // ... + } + test: yarn.#Run & { + // ... + } + // ... + } +} +``` + +When the above plan gets executed via `dagger up`, it produces the following output: + +```shell +dagger up dev.cue +[✔] inputs.directories.app 0.1s +[✔] actions.build 0.6s +[✔] actions.test 0.6s +``` + +Since these actions have run before, they are cached and take less than 1 second to complete. + +While the names used for the actions above - `build`, `test` - are short & descriptive, +any other names would have worked. Put differently, action naming does not affect plan execution. + +In the example above, the `build` action is an instance of the yarn package build definition. +This is written as `build: yarn.#Build` + +Default definition configuration can be modified via curly brackets, e.g. + +```cue + actions: { + build: yarn.#Build & { + // ... + } +``` + +We can build complex pipelines efficiently by referencing any definition, from any package in our actions. +This is one of the fundamental concepts that makes Dagger a powerful devkit for CI/CD. +Before we can use a package in a plan, we need to declare it at the top of the pipeline configuration, like this: + +```cue +import ( + "universe.dagger.io/yarn" +) +``` + +Since we are using the plan definition from the dagger package - `dagger.#Plan` - we also need to declare it at the top of the pipeline configuration: + +```cue +import ( + "dagger.io/dagger" + "universe.dagger.io/yarn" +) +``` + +Now that we understand the basics of a Dagger plan, we are ready to learn more about inputs and how to configure them. +This will enable us to configure plans just-in-time, which is something that typically happanes on every CI run.