split readme and contributing
This commit is contained in:
Conor Sloan
@@ -1,4 +1,53 @@
|
||||
# Publish Action Package
|
||||
<p align="center">
|
||||
<a href="https://github.com/ruchika-org/package-action"></a>
|
||||
</p>
|
||||
|
||||
# Package and Publish
|
||||
|
||||
This action packages your action repository as OCI artifacts and publishes it to [GHCR](ghcr.io), so your action can then be consumed as a package to make the actions ecosystem more secure.
|
||||
|
||||
The whole action repository is packaged by default. Set `path` input to specify which path you want to package if you want only a few folders (for eg. dist) to be packaged.
|
||||
|
||||
Make sure you use the [Starter Workflow] (https://github.com/actions-on-packages/.github) (TODO) to run the action and ensure you have the release trigger in the workflow where you use this action.
|
||||
|
||||
# Usage
|
||||
|
||||
<!-- start usage -->
|
||||
```yaml
|
||||
on:
|
||||
release:
|
||||
|
||||
- uses: immutable-actions/[email protected]
|
||||
with:
|
||||
|
||||
# Personal access token (PAT) or GITHUB_TOKEN with write:package scope used to upload the package to GHCR. The GITHUB_TOKEN is taken by default.
|
||||
#
|
||||
# We recommend using a service account with the least permissions necessary. Also
|
||||
# when generating a new PAT, select the least scopes necessary.
|
||||
#
|
||||
# [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
|
||||
#
|
||||
# Default: ${{ github.token }}
|
||||
token: ''
|
||||
|
||||
# Relative path of the working directory of the repository to be tar archived
|
||||
# and uploaded as OCI Artifact layer. You can mention multiple files/folders
|
||||
# by mentioning relative paths as space separated values.
|
||||
#
|
||||
# This defaults to the entire action repository contents if not explicitly defined.
|
||||
# Default: '.'
|
||||
path: 'src/ action.yml dist/'
|
||||
|
||||
|
||||
```
|
||||
<!-- end usage -->
|
||||
|
||||
# License
|
||||
|
||||
The scripts and documentation in this project are released under the [MIT License](LICENSE)
|
||||
|
||||
|
||||
# [Internal] Differences from previous implementation
|
||||
|
||||
This is a new implementation of an Action which publishes a given release to ghcr.io (GitHub Packages). It will eventually be moved to https://github.com/actions-on-packages/package-action and replace the existing implementation.
|
||||
|
||||
@@ -9,200 +58,3 @@ The key differences are:
|
||||
* This Action has the goal of generating provenance attestations for any release that is created.
|
||||
* This Action parses and validates that the release tag which triggered it is in a valid semver format, either `1.0.3-prerelease` or `v1.0.0-prerelease`.
|
||||
|
||||
## 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
|
||||
> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are
|
||||
> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or
|
||||
> [`nvm`](https://github.com/nvm-sh/nvm), this template has a `.node-version`
|
||||
> file at the root of the repository that will be used to automatically switch
|
||||
> to the correct version when you `cd` into the repository. Additionally, this
|
||||
> `.node-version` file is used by GitHub Actions in any `actions/setup-node`
|
||||
> actions.
|
||||
|
||||
1. :hammer_and_wrench: Install the dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
1. :building_construction: Package the TypeScript for distribution
|
||||
|
||||
```bash
|
||||
npm run bundle
|
||||
```
|
||||
|
||||
1. :white_check_mark: Run the tests
|
||||
|
||||
```bash
|
||||
$ npm test
|
||||
|
||||
PASS ./index.test.js
|
||||
✓ throws invalid number (3ms)
|
||||
✓ wait 500 ms (504ms)
|
||||
✓ test runs (95ms)
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
The [`src/`](./src/) directory is the heart of your action! This contains the
|
||||
source code that will be run when your action is invoked. You can replace the
|
||||
contents of this directory with your own code.
|
||||
|
||||
There are a few things to keep in mind when writing your action code:
|
||||
|
||||
- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
|
||||
In `main.ts`, you will see that the action is run in an `async` function.
|
||||
|
||||
```javascript
|
||||
import * as core from '@actions/core'
|
||||
//...
|
||||
|
||||
async function run() {
|
||||
try {
|
||||
//...
|
||||
} catch (error) {
|
||||
core.setFailed(error.message)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For more information about the GitHub Actions toolkit, see the
|
||||
[documentation](https://github.com/actions/toolkit/blob/master/README.md).
|
||||
|
||||
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 `src/` with your action code
|
||||
1. Add tests to `__tests__/` for your source code
|
||||
1. Format, test, and build the action
|
||||
|
||||
```bash
|
||||
npm run all
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
|
||||
> to build the final JavaScript action code with all dependencies included.
|
||||
> If you do not run this step, your action will not work correctly when it is
|
||||
> used in a workflow. This step also includes the `--license` option for
|
||||
> `ncc`, which will create a license file for all of the production node
|
||||
> modules used in your project.
|
||||
|
||||
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@v4
|
||||
|
||||
- name: Test Local Action
|
||||
id: test-action
|
||||
uses: ./
|
||||
with:
|
||||
milliseconds: 1000
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.test-action.outputs.time }}"
|
||||
```
|
||||
|
||||
For example workflow runs, check out the
|
||||
[Actions tab](https://github.com/actions/typescript-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@v4
|
||||
|
||||
- name: Test Local Action
|
||||
id: test-action
|
||||
uses: actions/typescript-action@v1 # Commit with the `v1` tag
|
||||
with:
|
||||
milliseconds: 1000
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.test-action.outputs.time }}"
|
||||
```
|
||||
|
||||
## Publishing a new release
|
||||
|
||||
This project includes a helper script designed to streamline the process of
|
||||
tagging and pushing new releases for GitHub Actions.
|
||||
|
||||
GitHub Actions allows users to select a specific version of the action to use,
|
||||
based on release tags. Our script simplifies this process by performing the
|
||||
following steps:
|
||||
|
||||
1. **Retrieving the latest release tag:** The script starts by fetching the most
|
||||
recent release tag by looking at the local data available in your repository.
|
||||
1. **Prompting for a new release tag:** The user is then prompted to enter a new
|
||||
release tag. To assist with this, the script displays the latest release tag
|
||||
and provides a regular expression to validate the format of the new tag.
|
||||
1. **Tagging the new release:** Once a valid new tag is entered, the script tags
|
||||
the new release.
|
||||
1. **Pushing the new tag to the remote:** Finally, the script pushes the new tag
|
||||
to the remote repository. From here, you will need to create a new release in
|
||||
GitHub and users can easily reference the new tag in their workflows.
|
||||
|
||||
Reference in New Issue
Block a user