From 3b329240012b7f536243ec557311cdd4ebe5dbf9 Mon Sep 17 00:00:00 2001 From: Jegan Kunniya Date: Thu, 26 Oct 2023 19:31:32 +0530 Subject: [PATCH 1/4] Updated the documentation to reflect on how to precisely reference local github action and more context on relative path --- .../finding-and-customizing-actions.md | 29 +------ .../workflow-syntax-for-github-actions.md | 86 ++++++++----------- ...cing-an-action-from-the-same-repository.md | 32 +++++++ 3 files changed, 71 insertions(+), 76 deletions(-) create mode 100644 data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md diff --git a/content/actions/learn-github-actions/finding-and-customizing-actions.md b/content/actions/learn-github-actions/finding-and-customizing-actions.md index 9e6fe2dc3ecd..06725bccff5b 100644 --- a/content/actions/learn-github-actions/finding-and-customizing-actions.md +++ b/content/actions/learn-github-actions/finding-and-customizing-actions.md @@ -69,34 +69,7 @@ An action's listing page includes the action's version and the workflow syntax r ### Adding an action from the same repository -If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. - -Example repository file structure: - -```shell -|-- hello-world (repository) -| |__ .github -| └── workflows -| └── my-first-workflow.yml -| └── actions -| |__ hello-world-action -| └── action.yml -``` - -Example workflow file: - -```yaml -jobs: - build: - runs-on: ubuntu-latest - steps: - # This step checks out a copy of your repository. - - uses: {% data reusables.actions.action-checkout %} - # This step references the directory that contains the action. - - uses: ./.github/actions/hello-world-action -``` - -The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in "[AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions)." +{% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %} ### Adding an action from a different repository diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index eb97d94cbd3f..959688ea3443 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -510,17 +510,7 @@ jobs: `./path/to/dir` -The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action. - -```yaml -jobs: - my_first_job: - steps: - - name: Check out repository - uses: {% data reusables.actions.action-checkout %} - - name: Use local my-action - uses: ./.github/actions/my-action -``` +{% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %} ### Example: Using a Docker Hub action @@ -633,16 +623,16 @@ You can also use a `run` step to run a script. For more information, see "[AUTOT You can override the default shell settings in the runner's operating system using the `shell` keyword. You can use built-in `shell` keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the `run` keyword. -| Supported platform | `shell` parameter | Description | Command run internally | -|--------------------|-------------------|-------------|------------------------| -| Linux / macOS | unspecified | The default shell on non-Windows platforms. Note that this runs a different command to when `bash` is specified explicitly. If `bash` is not found in the path, this is treated as `sh`. | `bash -e {0}` | -| All | `bash` | The default shell on non-Windows platforms with a fallback to `sh`. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | `bash --noprofile --norc -eo pipefail {0}` | -| All | `pwsh` | The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `pwsh -command ". '{0}'"` | -| All | `python` | Executes the python command. | `python {0}` | -| Linux / macOS | `sh` | The fallback behavior for non-Windows platforms if no shell is provided and `bash` is not found in the path. | `sh -e {0}` | -| Windows | `cmd` | {% data variables.product.prodname_dotcom %} appends the extension `.cmd` to your script name and substitutes for `{0}`. | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`. | -| Windows | `pwsh` | This is the default shell used on Windows. The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. If your self-hosted Windows runner does not have _PowerShell Core_ installed, then _PowerShell Desktop_ is used instead.| `pwsh -command ". '{0}'"`. | -| Windows | `powershell` | The PowerShell Desktop. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `powershell -command ". '{0}'"`. | +| Supported platform | `shell` parameter | Description | Command run internally | +| ------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| Linux / macOS | unspecified | The default shell on non-Windows platforms. Note that this runs a different command to when `bash` is specified explicitly. If `bash` is not found in the path, this is treated as `sh`. | `bash -e {0}` | +| All | `bash` | The default shell on non-Windows platforms with a fallback to `sh`. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | `bash --noprofile --norc -eo pipefail {0}` | +| All | `pwsh` | The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `pwsh -command ". '{0}'"` | +| All | `python` | Executes the python command. | `python {0}` | +| Linux / macOS | `sh` | The fallback behavior for non-Windows platforms if no shell is provided and `bash` is not found in the path. | `sh -e {0}` | +| Windows | `cmd` | {% data variables.product.prodname_dotcom %} appends the extension `.cmd` to your script name and substitutes for `{0}`. | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`. | +| Windows | `pwsh` | This is the default shell used on Windows. The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. If your self-hosted Windows runner does not have _PowerShell Core_ installed, then _PowerShell Desktop_ is used instead. | `pwsh -command ". '{0}'"`. | +| Windows | `powershell` | The PowerShell Desktop. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `powershell -command ". '{0}'"`. | ### Example: Running a command using Bash @@ -1164,35 +1154,35 @@ For more information about branch, tag, and path filter syntax, see "[`on. ### Patterns to match branches and tags -| Pattern | Description | Example matches | -|---------|------------------------|---------| -| `feature/*` | The `*` wildcard matches any character, but does not match slash (`/`). | `feature/my-branch`

`feature/your-branch` | -| `feature/**` | The `**` wildcard matches any character including slash (`/`) in branch and tag names. | `feature/beta-a/my-branch`

`feature/your-branch`

`feature/mona/the/octocat` | -| `main`

`releases/mona-the-octocat` | Matches the exact name of a branch or tag name. | `main`

`releases/mona-the-octocat` | -| `'*'` | Matches all branch and tag names that don't contain a slash (`/`). The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `main`

`releases` | -| `'**'` | Matches all branch and tag names. This is the default behavior when you don't use a `branches` or `tags` filter. | `all/the/branches`

`every/tag` | -| `'*feature'` | The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `mona-feature`

`feature`

`ver-10-feature` | -| `v2*` | Matches branch and tag names that start with `v2`. | `v2`

`v2.0`

`v2.9` | -| `v[12].[0-9]+.[0-9]+` | Matches all semantic versioning branches and tags with major version 1 or 2. | `v1.10.1`

`v2.0.0` | +| Pattern | Description | Example matches | +| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| `feature/*` | The `*` wildcard matches any character, but does not match slash (`/`). | `feature/my-branch`

`feature/your-branch` | +| `feature/**` | The `**` wildcard matches any character including slash (`/`) in branch and tag names. | `feature/beta-a/my-branch`

`feature/your-branch`

`feature/mona/the/octocat` | +| `main`

`releases/mona-the-octocat` | Matches the exact name of a branch or tag name. | `main`

`releases/mona-the-octocat` | +| `'*'` | Matches all branch and tag names that don't contain a slash (`/`). The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `main`

`releases` | +| `'**'` | Matches all branch and tag names. This is the default behavior when you don't use a `branches` or `tags` filter. | `all/the/branches`

`every/tag` | +| `'*feature'` | The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `mona-feature`

`feature`

`ver-10-feature` | +| `v2*` | Matches branch and tag names that start with `v2`. | `v2`

`v2.0`

`v2.9` | +| `v[12].[0-9]+.[0-9]+` | Matches all semantic versioning branches and tags with major version 1 or 2. | `v1.10.1`

`v2.0.0` | ### Patterns to match file paths Path patterns must match the whole path, and start from the repository's root. -| Pattern | Description of matches | Example matches | -|---------|------------------------|-----------------| -| `'*'` | The `*` wildcard matches any character, but does not match slash (`/`). The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `README.md`

`server.rb` | -| `'*.jsx?'` | The `?` character matches zero or one of the preceding character. | `page.js`

`page.jsx` | -| `'**'` | The `**` wildcard matches any character including slash (`/`). This is the default behavior when you don't use a `path` filter. | `all/the/files.md` | -| `'*.js'` | The `*` wildcard matches any character, but does not match slash (`/`). Matches all `.js` files at the root of the repository. | `app.js`

`index.js` -| `'**.js'` | Matches all `.js` files in the repository. | `index.js`

`js/index.js`

`src/js/app.js` | -| `docs/*` | All files within the root of the `docs` directory, at the root of the repository. | `docs/README.md`

`docs/file.txt` | -| `docs/**` | Any files in the `/docs` directory at the root of the repository. | `docs/README.md`

`docs/mona/octocat.txt` | -| `docs/**/*.md` | A file with a `.md` suffix anywhere in the `docs` directory. | `docs/README.md`

`docs/mona/hello-world.md`

`docs/a/markdown/file.md` -| `'**/docs/**'` | Any files in a `docs` directory anywhere in the repository. | `docs/hello.md`

`dir/docs/my-file.txt`

`space/docs/plan/space.doc` -| `'**/README.md'` | A README.md file anywhere in the repository. | `README.md`

`js/README.md` -| `'**/*src/**'` | Any file in a folder with a `src` suffix anywhere in the repository. | `a/src/app.js`

`my-src/code/js/app.js` -| `'**/*-post.md'` | A file with the suffix `-post.md` anywhere in the repository. | `my-post.md`

`path/their-post.md` | -| `'**/migrate-*.sql'` | A file with the prefix `migrate-` and suffix `.sql` anywhere in the repository. | `migrate-10909.sql`

`db/migrate-v1.0.sql`

`db/sept/migrate-v1.sql` | -| `'*.md'`

`'!README.md'` | Using an exclamation mark (`!`) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included. | `hello.md`

_Does not match_

`README.md`

`docs/hello.md` | -| `'*.md'`

`'!README.md'`

`README*` | Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths. | `hello.md`

`README.md`

`README.doc`| +| Pattern | Description of matches | Example matches | +| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| `'*'` | The `*` wildcard matches any character, but does not match slash (`/`). The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `README.md`

`server.rb` | +| `'*.jsx?'` | The `?` character matches zero or one of the preceding character. | `page.js`

`page.jsx` | +| `'**'` | The `**` wildcard matches any character including slash (`/`). This is the default behavior when you don't use a `path` filter. | `all/the/files.md` | +| `'*.js'` | The `*` wildcard matches any character, but does not match slash (`/`). Matches all `.js` files at the root of the repository. | `app.js`

`index.js` | +| `'**.js'` | Matches all `.js` files in the repository. | `index.js`

`js/index.js`

`src/js/app.js` | +| `docs/*` | All files within the root of the `docs` directory, at the root of the repository. | `docs/README.md`

`docs/file.txt` | +| `docs/**` | Any files in the `/docs` directory at the root of the repository. | `docs/README.md`

`docs/mona/octocat.txt` | +| `docs/**/*.md` | A file with a `.md` suffix anywhere in the `docs` directory. | `docs/README.md`

`docs/mona/hello-world.md`

`docs/a/markdown/file.md` | +| `'**/docs/**'` | Any files in a `docs` directory anywhere in the repository. | `docs/hello.md`

`dir/docs/my-file.txt`

`space/docs/plan/space.doc` | +| `'**/README.md'` | A README.md file anywhere in the repository. | `README.md`

`js/README.md` | +| `'**/*src/**'` | Any file in a folder with a `src` suffix anywhere in the repository. | `a/src/app.js`

`my-src/code/js/app.js` | +| `'**/*-post.md'` | A file with the suffix `-post.md` anywhere in the repository. | `my-post.md`

`path/their-post.md` | +| `'**/migrate-*.sql'` | A file with the prefix `migrate-` and suffix `.sql` anywhere in the repository. | `migrate-10909.sql`

`db/migrate-v1.0.sql`

`db/sept/migrate-v1.sql` | +| `'*.md'`

`'!README.md'` | Using an exclamation mark (`!`) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included. | `hello.md`

_Does not match_

`README.md`

`docs/hello.md` | +| `'*.md'`

`'!README.md'`

`README*` | Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths. | `hello.md`

`README.md`

`README.doc` | diff --git a/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md new file mode 100644 index 000000000000..af99800e9aaf --- /dev/null +++ b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md @@ -0,0 +1,32 @@ +If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. You must check out your repository before using the action. + +In case of `./path/to/dir` syntax, the path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`), unless the repository is checked out to a different location in the checkout step. + +Example repository file structure: + +```shell +|-- hello-world (repository) +| |__ .github +| └── workflows +| └── my-first-workflow.yml +| └── actions +| |__ hello-world-action +| └── action.yml +``` + +Example workflow file: + +```yaml +jobs: + my_first_job: + runs-on: ubuntu-latest + steps: + # This step checks out a copy of your repository. + - name: My first step - check out repository + uses: {% data reusables.actions.action-checkout %} + # This step references the directory that contains the action. + - name: Use local hello-world-action + uses: ./.github/actions/hello-world-action +``` + +The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in "[AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions)." From e5d5a9eff1dc701191f7304c0fede1687f8f4feb Mon Sep 17 00:00:00 2001 From: Jegan Kunniya Date: Thu, 26 Oct 2023 19:52:28 +0530 Subject: [PATCH 2/4] Contextualized the reusable content in terms of their respective reference locations --- .../finding-and-customizing-actions.md | 4 ++++ .../using-workflows/workflow-syntax-for-github-actions.md | 2 ++ ...ction-referencing-an-action-from-the-same-repository.md | 7 +------ 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/content/actions/learn-github-actions/finding-and-customizing-actions.md b/content/actions/learn-github-actions/finding-and-customizing-actions.md index 06725bccff5b..a87662839e92 100644 --- a/content/actions/learn-github-actions/finding-and-customizing-actions.md +++ b/content/actions/learn-github-actions/finding-and-customizing-actions.md @@ -69,8 +69,12 @@ An action's listing page includes the action's version and the workflow syntax r ### Adding an action from the same repository +If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. + {% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %} +The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in "[AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions)." + ### Adding an action from a different repository If an action is defined in a different repository than your workflow file, you can reference the action with the `{owner}/{repo}@{ref}` syntax in your workflow file. diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index 959688ea3443..64de39379fb1 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -510,6 +510,8 @@ jobs: `./path/to/dir` +The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action. + {% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %} ### Example: Using a Docker Hub action diff --git a/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md index af99800e9aaf..ebac440c5747 100644 --- a/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md +++ b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md @@ -1,7 +1,3 @@ -If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. You must check out your repository before using the action. - -In case of `./path/to/dir` syntax, the path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`), unless the repository is checked out to a different location in the checkout step. - Example repository file structure: ```shell @@ -13,6 +9,7 @@ Example repository file structure: | |__ hello-world-action | └── action.yml ``` +The path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`), unless the repository is checked out to a different location in the checkout step. Example workflow file: @@ -28,5 +25,3 @@ jobs: - name: Use local hello-world-action uses: ./.github/actions/hello-world-action ``` - -The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in "[AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions)." From 1c3bebf9075db303480194be8c070aad7642c307 Mon Sep 17 00:00:00 2001 From: Jegan Kunniya Date: Thu, 26 Oct 2023 20:03:40 +0530 Subject: [PATCH 3/4] fixed markdown MD031 rule failure --- .../section-referencing-an-action-from-the-same-repository.md | 1 + 1 file changed, 1 insertion(+) diff --git a/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md index ebac440c5747..569aba40f61c 100644 --- a/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md +++ b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md @@ -9,6 +9,7 @@ Example repository file structure: | |__ hello-world-action | └── action.yml ``` + The path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`), unless the repository is checked out to a different location in the checkout step. Example workflow file: From a8fa7a82bdd3450b00d9519bd2a12f44dc205bbe Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 1 Nov 2023 14:59:26 -0600 Subject: [PATCH 4/4] Update data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md --- .../section-referencing-an-action-from-the-same-repository.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md index 569aba40f61c..c4afb028ecf5 100644 --- a/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md +++ b/data/reusables/actions/workflows/section-referencing-an-action-from-the-same-repository.md @@ -10,7 +10,7 @@ Example repository file structure: | └── action.yml ``` -The path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`), unless the repository is checked out to a different location in the checkout step. +The path is relative (`./`) to the default working directory (`github.workspace`, `$GITHUB_WORKSPACE`). If the action checks out the repository to a location different than the workflow, the relative path used for local actions must be updated. Example workflow file: