Naming Your Workflow and Workflow Runs

Learn how to use the name and run-name keywords to give your GitHub Actions workflows and their runs meaningful, human-readable identifiers.

Introduction

When you work with GitHub Actions, every workflow and every execution of that workflow appears in the Actions tab of your repository. Without custom names, GitHub fills those entries with auto-generated strings that are hard to scan at a glance. Two keywords — name and run-name — solve that problem by letting you control exactly what is displayed.

Naming the Workflow with name

The name keyword sets the display name of the entire workflow as it appears in the Actions tab. It is placed at the top level of your workflow file, before any triggers or jobs:

With this line present, the Actions tab shows Pipeline instead of the raw file path such as .github/workflows/pipeline.yml.

If you omit the name keyword entirely, GitHub Actions falls back to using the workflow file path relative to the root of the repository as the display name.

Naming Individual Runs with run-name

While name identifies the workflow itself, run-name gives a unique label to each individual execution (run) of that workflow. This is useful when many runs accumulate and you need to identify them quickly — for example, knowing who triggered a deployment without opening each run.

The string above uses a context expression — ${{ github.actor }} — which GitHub Actions replaces at runtime with the username of the person or bot that triggered the run. A run triggered by the user gwstudent2 would therefore appear as:

Pipeline run by @gwstudent2

Understanding Context Expressions

The ${{ ... }} syntax is how GitHub Actions reads values from contexts at runtime. Contexts are structured data objects that GitHub provides for every workflow run. The github context is one of the most commonly used; it contains information about the event that triggered the workflow, the repository, and the actor who initiated the run.

Common properties of the github context:

Contexts are covered in depth in the next section of this course.

Complete Example

A minimal but complete workflow file demonstrating both keywords together:

When triggered by a push from the user gwstudent2, the Actions tab shows:

1. Workflow name: Pipeline
2. Run name: Pipeline run by @gwstudent2

Key Takeaways

1. Use name at the top level of a workflow file to set its display name in the Actions tab.
2. If name is absent, GitHub uses the file path relative to the repository root.
3. Use run-name to give each execution a descriptive label, optionally using context expressions.
4. Context expressions follow the ${{ context.property }} syntax and are evaluated at runtime.
5. The github context provides metadata about the triggering event, actor, branch, and repository.