Skip to content

Commit

Permalink
Release/v1 (#2)
Browse files Browse the repository at this point in the history 
* fix: codeowners

* chore: added aws sdk

* feat: send command action

* chore: build

* chore: delete test-action job

* test command arguments

* fix: getMultiline for commands input

* chore: mock multiline input

* chore: build

* fix: setup credentials

* test

* chore: comment local action

* docs: readme

* chore: lint

* chore: lint

* chore: lint
  • Loading branch information
@kyY00n
kyY00n authored Sep 16, 2024
1 parent 606009e commit bc9a5eb
Show file tree
Hide file tree
Showing 14 changed files with 123,164 additions and 464 deletions.
44 changes: 25 additions & 19 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,22 +43,28 @@ jobs:
- name: Test
id: npm-ci-test
run: npm run ci-test

test-action:
name: GitHub Actions Test
runs-on: ubuntu-latest

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 }}"
# test-action:
# name: GitHub Actions Test
# runs-on: ubuntu-latest
#
# steps:
# - name: Checkout
# id: checkout
# uses: actions/checkout@v4
#
# - name: Set up AWS Credentials
# uses: aws-actions/configure-aws-credentials@v4
# with:
# aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
# aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
# aws-region: ${{ secrets.AWS_REGION }}
#
# - name: Test Local Action
# id: test-action
# uses: ./
# with:
# instanceName: zipgo-prod-migrated
# workingDirectory: /home/ubuntu/ubuntu
# commands: |
# echo "hi"
# touch bye
2 changes: 1 addition & 1 deletion CODEOWNERS
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Repository CODEOWNERS

* @actions/actions-oss-maintainers
* @kyY00n
256 changes: 76 additions & 180 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,205 +1,101 @@
# Create a JavaScript Action
# SSM Send Command Action for GitHub Actions

[![GitHub Super-Linter](https://github.com/actions/javascript-action/actions/workflows/linter.yml/badge.svg)](https://github.com/super-linter/super-linter)
![CI](https://github.com/actions/javascript-action/actions/workflows/ci.yml/badge.svg)
This action sends commands to an EC2 instance via AWS Systems Manager (SSM). You
can use it to execute commands on your EC2 instances directly from your GitHub
Actions workflows.

Use this template to bootstrap the creation of a JavaScript action. :rocket:
## Example of Usage

This template includes compilation support, tests, a validation workflow,
publishing, and versioning guidance.
### Send Commands to an EC2 Instance

If you are new, there's also a simpler introduction in the
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
Before using this action, make sure to include the following

## 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
> [Node.js](https://nodejs.org) handy. If you are using a version manager like
> [`nodenv`](https://github.com/nodenv/nodenv) or
> [`nvm`](https://github.com/nvm-sh/nvm), you can run `nodenv install` in the
> root of your repository to install the version specified in
> [`package.json`](./package.json). Otherwise, 20.x or later should work!
1. :hammer_and_wrench: Install the dependencies

```bash
npm install
```

1. :building_construction: Package the JavaScript for distribution
```yaml
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
aws-region: us-east-1
```
```bash
npm run bundle
```
#### Send commands to an EC2 instance
1. :white_check_mark: Run the tests
```yaml
- name: Send commands to EC2 instance
uses: your-github-username/ssm-send-command-action@v1
with:
instanceName: my-ec2-instance
workingDirectory: /path/to/dir
commands: |
echo "Hello World"
ls -la
```
```bash
$ npm test
## Inputs
PASS ./index.test.js
✓ throws invalid number (3ms)
✓ wait 500 ms (504ms)
✓ test runs (95ms)
- `instanceId` (optional): The ID of the EC2 instance you want to connect to.
- `instanceName` (optional): The name of the EC2 instance you want to connect
to. If both `instanceId` and `instanceName` are provided, `instanceId` takes
precedence.
- `workingDirectory` (required): The working directory where you want to execute
commands.
- `commands` (required): The commands you want to execute on the instance.

...
```
## Outputs

## Update the Action Metadata
- `commandId`: The ID of the executed command.

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).
## Credentials

When you copy this repository, update `action.yml` with the name, description,
inputs, and outputs for your action.
This action relies on the
[AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials.html)
to determine AWS credentials and region. Use the
[aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials)
action to configure the GitHub Actions environment with appropriate AWS
credentials and region.

## Update the Action Code
```yaml
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
aws-region: us-east-1
```

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.
### Required Permissions

There are a few things to keep in mind when writing your action code:
Ensure that the IAM role or user associated with the AWS credentials has
permissions to execute SSM commands.

- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
In `main.js`, you will see that the action is run in an `async` function.
#### Example

```javascript
const core = require('@actions/core')
//...
Here’s the example IAM Policy you can use for running this GitHub Action:

async function run() {
try {
//...
} catch (error) {
core.setFailed(error.message)
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ssm:SendCommand",
"ssm:ListCommandInvocations",
"ssm:DescribeInstanceInformation"
],
"Resource": "*"
}
}
```

For more information about the GitHub Actions toolkit, see the
[documentation](https://github.com/actions/toolkit/blob/main/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/main/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:
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/javascript-action/actions)! :rocket:
## Usage
For details on the required permissions, see the
[AWS documentation on SSM](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-ssm-agent.html).

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.
## Troubleshooting

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.
### Command not executing

```yaml
steps:
- name: Checkout
id: checkout
uses: actions/checkout@v4
- name: Run my Action
id: run-action
uses: actions/javascript-action@v1 # Commit with the `v1` tag
with:
milliseconds: 1000

- name: Print Output
id: output
run: echo "${{ steps.run-action.outputs.time }}"
```
- Ensure that the `workingDirectory` exists on the instance and that you have
proper permissions.
- Verify that the `commands` input is correctly formatted.
Loading

0 comments on commit bc9a5eb

Please sign in to comment.