mirror of
https://github.com/actions/container-action.git
synced 2025-06-15 01:37:42 +00:00
Add steps and detail to README
This commit is contained in:
Nick Alteen
parent
ac219b2dcb
commit
137e75c6a6
219
README.md
219
README.md
@ -1,5 +1,220 @@
|
||||
# Container Action Template
|
||||
|
||||
To get started, click the `Use this template` button on this repository [which will create a new repository based on this template](https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/).
|
||||
[](https://github.com/super-linter/super-linter)
|
||||
|
||||
|
||||
For info on how to build your first Container action, see the [toolkit docs folder](https://github.com/actions/toolkit/blob/master/docs/container-action.md).
|
||||
Use this template to bootstrap the creation of a container action. :rocket:
|
||||
|
||||
This template includes compilation support, tests, a validation workflow,
|
||||
publishing, and versioning guidance.
|
||||
|
||||
If you are new, there's also a simpler introduction in the
|
||||
[Hello World Docker Action](https://github.com/actions/hello-world-docker-action)
|
||||
repository.
|
||||
|
||||
If you would like to use the
|
||||
[GitHub Actions Toolkit](https://github.com/actions/toolkit) in your container
|
||||
action, see the
|
||||
[Container Toolkit Action](https://github.com/actions/container-toolkit-action)
|
||||
repository.
|
||||
|
||||
## Create Your Own Action
|
||||
|
||||
To create your own action, you can use this repository as a template! Just
|
||||
follow the below instructions:
|
||||
|
||||
1. Click the **Use this template** button at the top of the repository
|
||||
1. Select **Create a new repository**
|
||||
1. Select an owner and name for your new repository
|
||||
1. Click **Create repository**
|
||||
1. Clone your new repository
|
||||
|
||||
## Initial Setup
|
||||
|
||||
After you've cloned the repository to your local machine or codespace, you'll
|
||||
need to perform some initial setup steps before you can develop your action.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> You'll need to have a reasonably modern version of
|
||||
> [Docker](https://www.docker.com/get-started/) handy (e.g. docker engine
|
||||
> version 20 or later).
|
||||
|
||||
1. :hammer_and_wrench: Build the container
|
||||
|
||||
Make sure to replace `actions/container-action` with an appropriate label for
|
||||
your container.
|
||||
|
||||
```bash
|
||||
docker build -t actions/container-action .
|
||||
```
|
||||
|
||||
1. :white_check_mark: Test the container
|
||||
|
||||
You can pass individual environment variables using the `--env` or `-e` flag.
|
||||
|
||||
```bash
|
||||
$ docker run --env INPUT_WHO_TO_GREET="Mona Lisa Octocat" actions/container-action
|
||||
|
||||
::notice file=entrypoint.sh,line=7::Hello, Mona Lisa Octocat!
|
||||
```
|
||||
|
||||
Or you can pass a file with environment variables using `--env-file`.
|
||||
|
||||
```bash
|
||||
$ cat ./.env.test
|
||||
INPUT_WHO_TO_GREET="Mona Lisa Octocat"
|
||||
|
||||
$ docker run --env-file ./.env.test actions/container-action
|
||||
|
||||
::notice file=entrypoint.sh,line=7::Hello, Mona Lisa Octocat!
|
||||
```
|
||||
|
||||
## Update the Action Metadata
|
||||
|
||||
The [`action.yml`](action.yml) file defines metadata about your action, such as
|
||||
input(s) and output(s). For details about this file, see
|
||||
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
|
||||
|
||||
When you copy this repository, update `action.yml` with the name, description,
|
||||
inputs, and outputs for your action.
|
||||
|
||||
## Update the Action Code
|
||||
|
||||
In this template, the container action runs a shell script,
|
||||
[`entrypoint.sh`](./entrypoint.sh), when the container is launched. Since you
|
||||
can choose any base Docker image and language you like, you can change this to
|
||||
suite your needs. There are a few main things to remember when writing code for
|
||||
container actions:
|
||||
|
||||
- Inputs are accessed using environment variables with the format
|
||||
`INPUT_<INPUT_NAME>`. For example, this action has an input called
|
||||
`who-to-greet`, which can be accessed in the entrypoint script using
|
||||
`INPUT_WHO_TO_GREET`.
|
||||
|
||||
```bash
|
||||
GREETING="Hello, $INPUT_WHO_TO_GREET!"
|
||||
```
|
||||
|
||||
- GitHub Actions supports a number of different workflow commands such as
|
||||
creating outputs, setting environment variables, and more. These are
|
||||
accomplished by writing to different `GITHUB_*` environment variables. For
|
||||
more information, see
|
||||
[Workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions).
|
||||
|
||||
| Scenario | Example |
|
||||
| --------------------- | ----------------------------------------------- |
|
||||
| Set environment vars | `echo "MY_VAR=my-value" >> "$GITHUB_ENV"` |
|
||||
| Set outputs | `echo "greeting=$GREETING" >> "$GITHUB_OUTPUT"` |
|
||||
| Prepend to `PATH` | `echo "$HOME/.local/bin" >> "$GITHUB_PATH"` |
|
||||
| Set `pre`/`post` vars | `echo "MY_VAR=my-value" >> "$GITHUB_STATE"` |
|
||||
| Set step summary | `echo "{markdown}" >> "$GITHUB_STEP_SUMMARY"` |
|
||||
|
||||
You can write multiline strings using the following syntax:
|
||||
|
||||
```bash
|
||||
{
|
||||
echo "JSON_RESPONSE<<EOF"
|
||||
curl https://example.com
|
||||
echo "EOF"
|
||||
} >> "$GITHUB_ENV"
|
||||
```
|
||||
|
||||
- Make sure that the script being run is executable!
|
||||
|
||||
```bash
|
||||
git add entrypoint.sh
|
||||
git update-index --chmod=+x entrypoint.sh
|
||||
```
|
||||
|
||||
So, what are you waiting for? Go ahead and start customizing your action!
|
||||
|
||||
1. Create a new branch
|
||||
|
||||
```bash
|
||||
git checkout -b releases/v1
|
||||
```
|
||||
|
||||
1. Replace the contents of `entrypoint.sh` with your action code
|
||||
1. Build and test the container
|
||||
|
||||
```bash
|
||||
docker build -t actions/container-action .
|
||||
docker run --env INPUT_WHO_TO_GREET="Mona Lisa Octocat" actions/container-action
|
||||
```
|
||||
|
||||
1. Commit your changes
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "My first action is ready!"
|
||||
```
|
||||
|
||||
1. Push them to your repository
|
||||
|
||||
```bash
|
||||
git push -u origin releases/v1
|
||||
```
|
||||
|
||||
1. Create a pull request and get feedback on your action
|
||||
1. Merge the pull request into the `main` branch
|
||||
|
||||
Your action is now published! :rocket:
|
||||
|
||||
For information about versioning your action, see
|
||||
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|
||||
in the GitHub Actions toolkit.
|
||||
|
||||
## Validate the Action
|
||||
|
||||
You can now validate the action by referencing it in a workflow file. For
|
||||
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
|
||||
action in the same repository.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
id: checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Test Local Action
|
||||
id: test-action
|
||||
uses: ./
|
||||
with:
|
||||
who-to-greet: Mona Lisa Octocat
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.test-action.outputs.greeting }}"
|
||||
```
|
||||
|
||||
For example workflow runs, check out the
|
||||
[Actions tab](https://github.com/actions/container-action/actions)! :rocket:
|
||||
|
||||
## Usage
|
||||
|
||||
After testing, you can create version tag(s) that developers can use to
|
||||
reference different stable versions of your action. For more information, see
|
||||
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|
||||
in the GitHub Actions toolkit.
|
||||
|
||||
To include the action in a workflow in another repository, you can use the
|
||||
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
|
||||
hash.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
id: checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Test Local Action
|
||||
id: test-action
|
||||
uses: actions/container-action@v1 # Commit with the `v1` tag
|
||||
with:
|
||||
who-to-greet: Mona Lisa Octocat
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.test-action.outputs.greeting }}"
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user