# Execute GitHub Actions workflows on Arm runners

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/servers-and-cloud-computing/github-actions-runner/)
- [About RunsOn and before you begin](https://learn.arm.com/learning-paths/servers-and-cloud-computing/github-actions-runner/before_you_begin/)
- [Install RunsOn in your AWS account](https://learn.arm.com/learning-paths/servers-and-cloud-computing/github-actions-runner/install-runs-on/)
- [Execute GitHub Actions workflows on Arm runners](https://learn.arm.com/learning-paths/servers-and-cloud-computing/github-actions-runner/execute-workflows/)
- [Next Steps](https://learn.arm.com/learning-paths/servers-and-cloud-computing/github-actions-runner/_next-steps/)

After installing RunsOn, you can execute jobs on Arm-based runners by modifying your GitHub Actions workflow files.

If you have existing GitHub Actions workflow files, you can simply change the `runs-on` setting.

For example, if you have a workflow file with:

```yaml
runs-on: ubuntu-22.04
```

You can change the `runs-on` value as shown below to invoke a new runner in your AWS account.

```yaml
runs-on:
  - runs-on
  - runner=1cpu-linux-arm64
  - run-id=${{ github.run_id }}
```

The runner is now an AWS EC2 Arm instance with 1 vCPU running Ubuntu 22.04.

That’s it! After about 30 seconds, you should see the job running on an Arm-based runner from your AWS account.

## Specify other EC2 instance types

You can also select other instance types, such as Graviton3 or Graviton4, by using the `family` parameter:

```yaml
jobs:
  build:
    runs-on:
      - runs-on
      - runner=2cpu-linux-arm64
      - family=r8g # Graviton4
      - run-id=${{ github.run_id }}
```

You can learn more about the supported Linux runners in the [official documentation](https://runs-on.com/runners/linux/).

If you would like to further customize the CPU count, RAM, disk sizes, and more, you can review the [job labels](https://runs-on.com/configuration/job-labels/).

## A complete GitHub Actions example

If you don’t have existing workflow files or want to try RunsOn by creating a new repository, you can run the commands below at a shell prompt. You will need Git (`git`) and the GitHub CLI (`gh`) installed. Refer to the [GitHub CLI installation instructions](https://cli.github.com/) if you don’t have the `gh` command installed.

Create a new directory for the repository:

```bash
mkdir actions-test ; cd actions-test
git init
mkdir -p .github/workflows
```

Use a text editor to save the workflow file below as a file named `test.yml` in the `.github/workflows/` directory:

```yaml
name: test

on:
  push:
  workflow_dispatch:

jobs:
  build:
    runs-on:
      - runs-on
      - runner=1cpu-linux-arm64
      - run-id=${{ github.run_id }}
    steps:
      - run: echo "Hello from your Arm runner!"
```

Add the workflow file to the repository, and commit the changes:

```bash
git add .github/workflows/test.yml
git commit -m "initial commit for actions test"
```

Authorize GitHub so you can access your account from the command line:

```bash
gh auth login
```

Use a browser or authentication token to authorize your GitHub account.

Create the repository:

```bash
gh repo create actions-test --private --source=. --remote=origin
```

Save the project to GitHub:

```bash
git push -u origin master
```

The `git push` command will trigger the GitHub Action to run.

You can use a browser to view the Actions tab for the repository and see the job.

You can also see the result from the command line:

```bash
gh run list
```

Look at the output and find the ID. The output will be similar to:

```
STATUS  TITLE                            WORKFLOW  BRANCH  EVENT  ID           ELAPSED  AGE
✓       initial commit for actions test  test      master  push   10777854144  43s      about 6 minutes ago
```

Print the log for the run. Substitute your job ID for the example ID shown below.

```bash
gh run view 10777854144 --log
```

You will see numerous details about the run, including architecture, instance name, region, instance type, and the name of the AMI (disk image).

You will also see that the instance is a spot instance (for lowest price).

```
build	Set up job	2024-09-09T17:05:20.0155475Z Current runner version: '2.319.1'
build	Set up job	2024-09-09T17:05:20.0163810Z Runner name: 'runs-on--i-03421942a716b3f2a--vPaXOcNxGv'
build	Set up job	2024-09-09T17:05:20.0164922Z Runner group name: 'Default'
build	Set up job	2024-09-09T17:05:20.0165868Z Machine name: 'ip-10-1-44-45'
build	Set up job	2024-09-09T17:05:20.0187255Z ##[group]Runner Instance
build	Set up job	2024-09-09T17:05:20.0188268Z |       INFO        |                      VALUE                      |
build	Set up job	2024-09-09T17:05:20.0190247Z |-------------------|-------------------------------------------------|
build	Set up job	2024-09-09T17:05:20.0191195Z | SSH               | ssh runner@XX.XX.XXX.XX                         |
build	Set up job	2024-09-09T17:05:20.0194360Z | Region            | us-west-2                                       |
build	Set up job	2024-09-09T17:05:20.0195723Z | AvailabilityZone  | us-west-2c                                      |
build	Set up job	2024-09-09T17:05:20.0196761Z | Version           | v2.5.0                                          |
build	Set up job	2024-09-09T17:05:20.0197751Z | Runner            | runs-on--i-03421942a716b3f2a--vPaXOcNxGv        |
```

You are now able to run GitHub Actions workflows on Graviton-based EC2 instances in your AWS account.