---
title: "Alpacon Exec Action"
description: "Run commands on remote servers from GitHub Actions with Alpacon Exec Action. Learn how to pass scripts and environment variables and choose a server account."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Alpacon Exec Action

Alpacon Exec Action runs shell commands on remote servers in your workspace. It runs each line of your script as a separate [`alpacon exec`](/reference/cli/exec/) command. You can choose a server account and pass environment variables.

  Update `uses: alpacax/alpacon-websh-action@v1` to `uses: alpacax/alpacon-exec-action@v2`, and rename the `api-token` input to `service-token`. GitHub does not redirect `uses:` references when an action repository is renamed, so workflows using the old name fail with `repository not found`.

## Inputs

| Name | Description | Required | Default |
|------|-------------|----------|---------|
| `workspace-url` | Alpacon workspace URL | Yes | |
| `service-token` | Alpacon service token key (`alpst-`) | Yes | |
| `target` | Target server name | Yes | |
| `script` | Shell command or script to execute | Yes | |
| `username` | The application's server account to run the command as | No | |
| `groupname` | Group override (ignored for a service token; the command runs in the service account's private group) | No | |
| `env` | Environment variables (one per line, `KEY=VALUE` or `KEY` format) | No | |

## Usage

### Basic command execution

```yaml
- name: Deploy application
  uses: alpacax/alpacon-exec-action@v2
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    service-token: ${{ secrets.ALPACON_SERVICE_TOKEN }}
    target: 'prod-server'
    username: 'ci-deploy'
    script: |
      cd /opt/myapp && git pull && npm install && pm2 restart app
```

### Execute as the application account

```yaml
- name: Copy files as the application account
  uses: alpacax/alpacon-exec-action@v2
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    service-token: ${{ secrets.ALPACON_SERVICE_TOKEN }}
    target: 'web-server'
    username: 'ci-deploy'
    script: cp -r /tmp/build/. /home/ci-deploy/app/public/
```

### Pass environment variables

```yaml
- name: Run with environment variables
  uses: alpacax/alpacon-exec-action@v2
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    service-token: ${{ secrets.ALPACON_SERVICE_TOKEN }}
    target: 'prod-server'
    username: 'ci-deploy'
    env: |
      APP_ENV=production
      DB_HOST=localhost
      LOG_LEVEL=info
    script: |
      echo "Deploying to $APP_ENV"
      sudo systemctl restart myapp
```

The `env` input supports two formats:
- `KEY=VALUE`: sets the variable to the specified value
- `KEY`: forwards the variable from the runner environment

## Notes

- Requires [`alpacon-setup-action`](/reference/actions/setup/) to run first
- Keep dependent shell operations on one line, such as `cd /opt/myapp && git pull`
- Empty lines and comment-only lines (starting with `#`) are skipped
- `groupname` is ignored for a service token: the command runs in the service account's private group
- The system-service example needs the [sudo settings and command rule](/integrate/github-actions/#restart-services-with-sudo)

## See also

- [Actions reference overview](/reference/actions/)
- [alpacon-setup-action](/reference/actions/setup/)
- [alpacon-cp-action](/reference/actions/cp/)
- [alpacon-common-action](/reference/actions/common/)

## Resources

- [GitHub Marketplace](https://github.com/marketplace/actions/alpacon-exec-action)
- [Source code](https://github.com/alpacax/alpacon-exec-action)

Source: https://docs.alpacax.com/reference/actions/exec/
