# How to Run a Specific Job in a GitHub Actions Workflow Using `act --job`

> Learn to run a specific GitHub Actions job with the act --job flag. Execute only your chosen job and its dependencies, skipping others. Streamline your CI/CD testing.

- Repository: [nektos/act](https://github.com/nektos/act)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Use the `-j` or `--job` flag followed by the job ID to execute only that job and its dependencies, skipping all other jobs in the workflow.**

The `nektos/act` CLI tool allows you to run GitHub Actions workflows locally for testing and debugging. When you want to iterate on a single job without executing the entire workflow graph, the `--job` flag provides precise control over what runs on your machine.

## Flag Definition and CLI Parsing

The `--job` flag is registered in the root command definition located in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go). At line 73, the flag is declared with a short alias `-j`:

```go
rootCmd.Flags().StringP("job", "j", "", "run a specific job ID")

```

When you execute a run command, the value is retrieved inside `newRunCommand` at lines 56-57:

```go
jobID, err := cmd.Flags().GetString("job")

```

If a non-empty `jobID` is provided, `act` bypasses the default full-workflow planning and instead builds a targeted execution plan.

## Building a Filtered Execution Plan

The filtering logic resides in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go) where the planner switches modes based on the presence of a job ID. At lines 99-100 and again at lines 51-54, the code checks for the flag and calls `PlanJob`:

```go
if jobID != "" {
    filterPlan, plannerErr = planner.PlanJob(jobID)
}

```

The `PlanJob` method in [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go) (lines 31-45) constructs a plan containing only the requested job and its required predecessors:

```go
func (wp *workflowPlanner) PlanJob(jobName string) (*Plan, error) {
    plan := new(Plan)
    for _, w := range wp.workflows {
        stages, err := createStages(w, jobName)
        // ...
    }
    return plan, lastErr
}

```

Unlike the standard planning mode which executes all jobs triggered by an event, `PlanJob` invokes `createStages` with a specific target, resulting in a minimal execution graph.

## Dependency Resolution Algorithm

The heavy lifting occurs in `createStages` within [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go) (lines 44-78). This function performs two critical operations:

1. **Collects transitive dependencies** – It recursively follows the `needs` graph of the requested job, building a complete list of all jobs that must run first.

2. **Constructs execution stages** – Jobs with satisfied dependencies are grouped into stages that run in parallel, respecting the dependency order.

Key implementation details from the source:

```go
// Gather the transitive closure of required jobs
jobDependencies := make(map[string][]string)
for len(jobIDs) > 0 {
    // ...
    jobDependencies[jID] = job.Needs()
    // ...
}

// Construct stages respecting dependencies
for len(jobDependencies) > 0 {
    stage := new(Stage)
    for jID, jDeps := range jobDependencies {
        if listInStages(jDeps, stages...) { // all deps already staged?
            stage.Runs = append(stage.Runs, &Run{Workflow: w, JobID: jID})
            delete(jobDependencies, jID)
        }
    }
    // ...
}

```

The dependency data originates from the `Job` struct defined in [`pkg/model/workflow.go`](https://github.com/nektos/act/blob/main/pkg/model/workflow.go) (line 196), which includes the `Needs []string` field:

```go
type Job struct {
    ID    string
    Needs []string // ← list of job IDs this job depends on
    // ...
}

```

The `Needs()` method returns this slice, enabling the planner to walk the dependency graph and ensure prerequisites execute before the target job.

## Practical Usage Examples

Before targeting a specific job, enumerate available job IDs using the list command:

```bash

# List all jobs defined in the workflows

act --list

```

Execute a single job by its ID. This automatically includes any jobs defined in its `needs` configuration:

```bash

# Run only the job named 'test' (and any jobs it needs)

act -j test

```

Combine the job filter with an explicit event trigger when workflows have multiple entry points:

```bash

# Trigger on push event but only run the 'build' job

act push -j build

```

Preview the execution plan without running containers using the dry-run flag:

```bash

# Debug the plan (shows the stages that will be executed)

act -j lint --dryrun

```

## Summary

- The **`--job` (or `-j`) flag** in `nektos/act` limits execution to a specific job ID and its dependency chain.
- Flag parsing occurs in [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go), while plan construction happens in [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go) via the `PlanJob` method.
- The `createStages` algorithm resolves transitive dependencies by traversing the `needs` graph defined in [`pkg/model/workflow.go`](https://github.com/nektos/act/blob/main/pkg/model/workflow.go).
- Jobs are organized into parallel **stages** where all dependencies within a stage are satisfied before proceeding to the next stage.
- This targeted approach significantly speeds up local debugging by skipping unrelated workflow jobs.

## Frequently Asked Questions

### How do I find the correct job ID to use with `act --job`?

Run `act --list` to display all available job IDs from your workflow files. The ID corresponds to the key name under the `jobs:` section in your YAML file, not the `name:` field. According to the implementation in [`cmd/list.go`](https://github.com/nektos/act/blob/main/cmd/list.go), this enumerates all jobs the planner can detect.

### Does `act --job` run dependent jobs automatically?

Yes. When you specify a job ID, `act` builds a filtered plan that includes the target job plus every job listed in its `needs` array, recursively. As implemented in [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go), the `createStages` function calculates the transitive closure of dependencies, ensuring prerequisites execute first.

### Can I run multiple specific jobs at once using the flag?

No. The `--job` flag accepts a single string value and calls `planner.PlanJob` with that specific ID. To run multiple unrelated jobs, you must execute separate `act` commands or allow the default full-plan execution and use other filtering mechanisms like `--graph` visualization.

### What happens if I specify a job ID that does not exist?

If the job ID is not found in the workflow files, `PlanJob` in [`pkg/model/planner.go`](https://github.com/nektos/act/blob/main/pkg/model/planner.go) returns an error, and `act` exits with a planner error before attempting to run any containers. The CLI validates the job exists during the planning phase at lines 51-54 and 99-100 of [`cmd/root.go`](https://github.com/nektos/act/blob/main/cmd/root.go).