diff --git a/docs/ja/user-guide/configuration/sourceDirectory.md b/docs/ja/user-guide/configuration/sourceDirectory.md index f713e4a6..17267d2d 100644 --- a/docs/ja/user-guide/configuration/sourceDirectory.md +++ b/docs/ja/user-guide/configuration/sourceDirectory.md @@ -8,7 +8,7 @@ toc: url: "#ソースディレクトリ" --- # ソースディレクトリ -ソースディレクトリはパイプラインのベースとなるカスタムディレクトリを指定できます。ScrewdriverのUIでパイプラインを作成したときや、ディレクトリを追加するために現在のパイプラインをを更新するときに指定可能です。これは[monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git)のサブディレクトリに基づいてワークフローを実行する際に有用です。カスタムソースディレクトリを使えば、単一のリポジトリで複数パイプラインを作成することが可能です。 +ソースディレクトリはパイプラインのベースとなるカスタムディレクトリを指定できます。ScrewdriverのUIでパイプラインを作成したときや、ディレクトリを追加するために現在のパイプラインをを更新するときに指定可能です。これは[monorepo](https://www.atlassian.com/git/tutorials/monorepos)のサブディレクトリに基づいてワークフローを実行する際に有用です。カスタムソースディレクトリを使えば、単一のリポジトリで複数パイプラインを作成することが可能です。 ### ソースディレクトリのフォーマット ディレクトリパスはリポジトリのルートからの相対パスとなります。ソースディレクトリの下には`screwdriver.yaml`が一つ有る必要があります。 diff --git a/docs/ja/user-guide/configuration/sourcePaths.md b/docs/ja/user-guide/configuration/sourcePaths.md index 1dfc314d..d40ec673 100644 --- a/docs/ja/user-guide/configuration/sourcePaths.md +++ b/docs/ja/user-guide/configuration/sourcePaths.md @@ -10,7 +10,7 @@ toc: # ソースパス -ソースパス機能を使うことで、特定のソースコードが更新された場合にのみジョブをトリガーすることができます。ジョブ定義の中で `sourcePaths` を文字列、または文字列の配列で設定することで利用できます。この機能は [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git) のサブディレクトリに基づいたワークフローを実現するのに役立ちます。 +ソースパス機能を使うことで、特定のソースコードが更新された場合にのみジョブをトリガーすることができます。ジョブ定義の中で `sourcePaths` を文字列、または文字列の配列で設定することで利用できます。この機能は [monorepo](https://www.atlassian.com/git/tutorials/monorepos) のサブディレクトリに基づいたワークフローを実現するのに役立ちます。 ### ソースパスの種類 diff --git a/docs/user-guide/configuration/sourceDirectory.md b/docs/user-guide/configuration/sourceDirectory.md index 38345984..c1dce7d5 100644 --- a/docs/user-guide/configuration/sourceDirectory.md +++ b/docs/user-guide/configuration/sourceDirectory.md @@ -9,7 +9,7 @@ toc: --- # Source Directory -Source directory can be used to specify a custom directory that a pipeline is based upon. You can specify it when you create the pipeline in Screwdriver UI or update your current pipeline to add the directory. This can be useful for running workflows based on subdirectories in a [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git). With custom source directory, now you can create multiple pipelines on a single repository. +Source directory can be used to specify a custom directory that a pipeline is based upon. You can specify it when you create the pipeline in Screwdriver UI or update your current pipeline to add the directory. This can be useful for running workflows based on subdirectories in a [monorepo](https://www.atlassian.com/git/tutorials/monorepos). With custom source directory, now you can create multiple pipelines on a single repository. ### Source Directory format The directory path is relative to the root of the repository. You must have a `screwdriver.yaml` under your source directory. diff --git a/docs/user-guide/configuration/sourcePaths.md b/docs/user-guide/configuration/sourcePaths.md index 856bf5f0..80fcbc63 100644 --- a/docs/user-guide/configuration/sourcePaths.md +++ b/docs/user-guide/configuration/sourcePaths.md @@ -9,7 +9,7 @@ toc: --- # Source Paths -Source paths can be used to specify source code paths that will trigger a job upon modification. This is done by using a `sourcePaths` keyword in your job definition as a string or array of strings. This can be useful for running workflows based on subdirectories in a [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git). +Source paths can be used to specify source code paths that will trigger a job upon modification. This is done by using a `sourcePaths` keyword in your job definition as a string or array of strings. This can be useful for running workflows based on subdirectories in a [monorepo](https://www.atlassian.com/git/tutorials/monorepos). ### Types of source paths You can either specify subdirectories and/or specific files as source paths. To denote a subdirectory, leave a trailing slash (`/`) at the end. The path is relative to the root of the repository. diff --git a/docs/user-guide/templates/job-templates.md b/docs/user-guide/templates/job-templates.md index ed659a66..333aaa3e 100644 --- a/docs/user-guide/templates/job-templates.md +++ b/docs/user-guide/templates/job-templates.md @@ -220,6 +220,7 @@ jobs: requires: [~pr, ~commit] image: node:lts main2: + template: sd/noop@latest annotations: screwdriver.cd/mergeSharedSteps: true requires: [main] @@ -239,6 +240,7 @@ jobs: - pretest: npm lint - test: npm test main2: + template: sd/noop@latest annotations: screwdriver.cd/mergeSharedSteps: true requires: [main] diff --git a/docs/user-guide/templates/pipeline-templates.md b/docs/user-guide/templates/pipeline-templates.md index 51e2dedb..c9778d47 100644 --- a/docs/user-guide/templates/pipeline-templates.md +++ b/docs/user-guide/templates/pipeline-templates.md @@ -8,8 +8,11 @@ toc: url: "#pipeline-templates" - title: Finding templates url: "#finding-pipeline-templates" - - title: Using a template + - title: Using a pipeline template url: "#using-a-pipeline-template" + - title: Customization + url: "#customization" + subitem: true - title: Example pipeline template url: "#example-pipeline-template" - title: "Version/Tag Semantics" @@ -85,6 +88,90 @@ If no template version is specified, the most recently published will be used. T The most reliable way to avoid unexpected template changes is to refer to a specific version of the template. For instance, `nodejs/test@1.0.4` is an immutable reference to a particular list of steps. Using a reference such as `nodejs/test@1.0` means that a job will automatically use `nodejs/test@1.0.5` when it becomes available, but that comes with risk of an unexpected change in behavior. +### Customization +Some customization can be done within the `jobs` configuration when using a Pipeline Template. + +For user-defined jobs with names that *already exist* in the pipeline template, customization is limited to a set of certain fields: `image`, `settings`, `environment`, and `requires`. + +For user-defined jobs with names that *do not already exist* in the pipeline template, all jobs fields are allowed. + +#### Example +Given a pipeline template: + +``` +shared: + image: node:lts + environment: + VAR1: "one" + VAR2: "two" + steps: + - init: npm install + - test: npm test + settings: + email: [test@email.com, test2@email.com] + slack: 'mychannel' +jobs: + main: + requires: [~pr, ~commit] + second: + requires: [main] +``` + +And user defined yaml: + +``` +template: sd-test/example-template@latest +jobs: + main: + requires: [~commit] + image: node:20 + settings: + email: [test@email.com, test3@email.com] + environment: + VAR3: "three" + VAR1: "empty" + third: + requires: [] + image: node:lts + steps: + - echo: echo third job +``` + +Resulting config would be: +``` +jobs: + main: + requires: [~commit] + image: node:20 + steps: + - init: npm install + - test: npm test + environment: + VAR1: "empty" + VAR2: "two" + VAR3: "three" + settings: + email: [test@email.com, test3@email.com] + slack: 'mychannel' + second: + requires: [main] + image: node:lts + steps: + - init: npm install + - test: npm test + environment: + VAR1: "one" + VAR2: "two" + settings: + email: [test@email.com, test2@email.com] + slack: 'mychannel' + third: + requires: [] + image: node:lts + steps: + - echo: echo third job +``` + ## Version/Tag Semantics Template versions can be referenced in a variety of ways that express users' trade-off between an unchanging set of steps and automatically using improvements that a template's maintainers have added. As above, these examples reference nodejs/test template. @@ -113,14 +200,14 @@ shared: environment: FOO: bar jobs: - main: - image: node:lts - requires: [~pr, ~commit] - steps: - - install: npm install - - test: npm test - secrets: - - NPM_TOKEN + main: + image: node:lts + requires: [~pr, ~commit] + steps: + - install: npm install + - test: npm test + secrets: + - NPM_TOKEN ``` ## Creating a template @@ -172,27 +259,27 @@ Example `screwdriver.yaml`: ```yaml shared: - image: node:lts + image: node:lts jobs: main: - requires: [~pr, ~commit] - steps: - - validate: npx -y -p screwdriver-template-main pipeline-template-validate - environment: - SD_TEMPLATE_PATH: ./path/to/template.yaml + requires: [~pr, ~commit] + steps: + - validate: npx -y -p screwdriver-template-main pipeline-template-validate + environment: + SD_TEMPLATE_PATH: ./path/to/template.yaml publish: - requires: [main] - steps: - - publish: npx -y -p screwdriver-template-main pipeline-template-publish - - tag: npx -y -p screwdriver-template-main pipeline-template-tag --namespace myNamespace --name template_name --version 1.3.0 --tag stable - environment: - SD_TEMPLATE_PATH: ./path/to/template.yaml + requires: [main] + steps: + - publish: npx -y -p screwdriver-template-main pipeline-template-publish + - tag: npx -y -p screwdriver-template-main pipeline-template-tag --namespace myNamespace --name template_name --version 1.3.0 --tag stable + environment: + SD_TEMPLATE_PATH: ./path/to/template.yaml remove: - steps: - - remove: npx -y -p screwdriver-template-main pipeline-template-remove --namespace myNamespace --name template_name + steps: + - remove: npx -y -p screwdriver-template-main pipeline-template-remove --namespace myNamespace --name template_name remove_tag: - steps: - - remove_tag: npx -y -p screwdriver-template-main pipeline-template-remove-tag --namespace myNamespace --name template_name --tag stable + steps: + - remove_tag: npx -y -p screwdriver-template-main pipeline-template-remove-tag --namespace myNamespace --name template_name --tag stable ``` Create a Screwdriver pipeline with your template repo and start the build to validate and publish it.