https://github.com/actions/container-prebuilt-action
https://github.com/actions/container-prebuilt-action
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/actions/container-prebuilt-action
- Owner: actions
- License: mit
- Created: 2023-12-08T14:55:49.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-18T21:02:01.000Z (3 months ago)
- Last Synced: 2026-02-25T17:30:37.728Z (3 months ago)
- Language: Dockerfile
- Size: 94.7 KB
- Stars: 12
- Watchers: 3
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Create a Container Prebuilt Action
[](https://github.com/super-linter/super-linter)
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. The core difference between this template
and [`actions/container-action`](https://github.com/actions/container-action) is
that this template does not build the container image on every action run.
Instead, the action pulls the image from
[GitHub Container Registry (ghcr.io)](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).
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
> [!IMPORTANT]
>
> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For
> details on how to use this file, see
> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
## 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-prebuilt-action` with an appropriate
label for your container.
```bash
docker build -t actions/container-prebuilt-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-prebuilt-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-prebuilt-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.
> [!IMPORTANT]
>
> Make sure to update the `image` property to use your repository!
>
> ```yaml
> runs:
> using: docker
> image: docker://ghcr.io//:
> ```
## 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 argument identifiers or environment variables
(depending on what you set in your `action.yml`). For example, the first input
to this action, `who-to-greet`, can be accessed in the entrypoint script using
the `$INPUT_WHO_TO_GREET` environment variable.
```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<> "$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-prebuilt-action .
docker run actions/container-prebuilt-action "Mona Lisa Octocat"
```
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/main/docs/action-versioning.md)
in the GitHub Actions toolkit.
## Releasing Versions
By default, the [`cd.yml` workflow](./.github/workflows/cd.yml) in this
repository is configured to release a new version of the action any time a pull
request is merged into the default branch (`main`). In order to prevent existing
versions from being overwritten, the
[`version-check.yml` workflow](./.github/workflows/version-check.yml) can be
used as a
[required status check](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging)
in your branch protection rules.
As part of the pull request, make sure to update the
[`.version` file](./.version) to a new [Semantic Version](https://semver.org/).
## 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/main/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@v4
- name: Test Local Action
id: test-action
uses: actions/container-prebuilt-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 }}"
```