# Quickstart {#quickstart}

This page walks you through getting Takumi Runner set up and running your first workflow.

## Prerequisites {#prerequisites}

To use Takumi Runner, the following conditions must be met:

- You have a Shisho Cloud organization and a user account belonging to it
- You have a GitHub Organization and admin permissions on it
- Your Takumi subscription is active
- The user performing initial setup (enabling the Runner feature, installing the GitHub App, etc.) has the **Takumi Manager** and **API Integration Manager** roles in Shisho Cloud
- The user viewing dashboards and job execution history has the **Takumi Runner User** role in Shisho Cloud

:::info
Using Takumi Runner with **public repositories** requires enabling the **Allow public repositories** option in the GitHub Organization's runner group settings (**Settings** > **Actions** > **Runner groups**). This option is disabled by default, so verify and update it during Takumi Runner setup. Without it, jobs remain in `queued` state indefinitely. See [GitHub documentation](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups) for details. Note that workflow runs triggered by contributors outside your organization are also billed to your organization.
:::

## Steps {#steps}

### 1. Enable the Runner Feature {#enable-runner}

Open **Runner** from the Shisho Cloud console sidebar and go to the **Setup** tab. A setup wizard will appear — complete the first step to **enable the Runner feature**.

![Runner setup wizard](/docs/_md-assets/89a95f2709-setup-wizard.png)

### 2. Install the GitHub App {#install-github-app}

In the next step of the setup wizard, click the **Install GitHub App** button. You will be redirected to the GitHub installation page.

1. Select the scope for which to enable the Runner:
   - Choose **All repositories** to enable for all repositories
   - Choose **Only select repositories** to enable for specific repositories only
2. Click **Install** to complete the installation

:::info
Installing the GitHub App requires **Owner** permissions on the GitHub Organization. If you do not have the required permissions, request the installation from the Organization admin. After admin approval, you can link the app from the Shisho Cloud console under **Settings** > **Service Integrations** > **CI/CD Integration** by selecting **Link existing GitHub App**.
:::

For details on the access permissions the GitHub App requests, see [GitHub Integration > GitHub App Permissions](/docs/t/runner/architecture/integration.md#permissions).

### 3. Edit Your Workflow File {#edit-workflow}

Change `runs-on` to `takumi-runner` in your existing workflow file (`.github/workflows/*.yml`):

```yaml
jobs:
  build:
    runs-on: takumi-runner
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm test
```

### 4. Run the Workflow {#run-workflow}

Push code or trigger the workflow manually on GitHub. Takumi Runner will automatically pick up the job and run it on a secure VM.

### 5. Check the Traces {#check-traces}

Once the workflow completes, the job execution history appears under **Runner** > **Jobs** in the Shisho Cloud console.

![Job list](/docs/_md-assets/cb59957231-jobs-list.png)

Click a job to view the overview screen, where you can see process executions, network connections, and file accesses.

![Job overview](/docs/_md-assets/3e444a586b-job-overview.png)

The **Timeline** tab shows each workflow step and its associated traces.

![Job timeline](/docs/_md-assets/df92b4d670-job-timeline.png)

## Next Steps {#next-steps}

- For details on trace data, see [Trace Collection](/docs/t/runner/features/trace-collection.md)
- To review execution history, see [Job History](/docs/t/runner/observability/job-history.md)