Managing a workflow run

You can view the status and results of each step in your workflow, cancel a pending workflow, debug and re-run a failed workflow, search and download logs, and download artifacts.

GitHub Actions is currently in limited public beta and is subject to change. We strongly recommend that you do not use this feature for high-value workflows and content during the beta period. For more information about the beta, see "About GitHub Actions."

For more information about using GitHub Actions, see "Automating your workflow with GitHub Actions."

In this article

About workflow permissions

Anyone with read access for a GitHub Actions-enabled repository can see all information about a workflow. Read access allows you to download artifacts and view workflow files, run history, and logs.

You must have at least write-level access to cancel or re-run workflow runs.

For more information, see "Access permissions on GitHub."

About workflow management

You can see whether a workflow run is in progress or complete from the workflow run page. If the run is in progress, you can cancel the run. If the run is complete, you can see whether the result was a success, failure, canceled, or neutral. If the run failed, you can view and search the build logs to diagnose the failure and re-run the workflow. You can also download logs and build artifacts.

Annotated workflow run image

GitHub Actions use the Checks API to output statuses, results, and logs for a workflow. GitHub creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps. GitHub Actions are run as a step in a workflow. For more information about the Checks API, see "Checks" in the GitHub Developer documentation.

Viewing your workflow history

You can view each job in a workflow run and each step in a job. For more information, see "About GitHub Actions."

Every job includes a "Set up Job" step and a "Complete job" step by default, and the actions configured in the workflow file.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Actions.

    Actions tab in the main repository navigation

  3. In the left sidebar, click the workflow you want to see.

    Workflow list in left sidebar

  4. Under "Workflow runs", click the name of the run you want to see.

    Name of workflow run

  5. Optionally, if the run failed, to re-run the workflow, in the upper-right corner of the workflow, use the Re-run checks drop-down menu, and select Re-run all checks.

    Re-run checks drop-down menu

Canceling a workflow run

When you cancel a workflow run, GitHub cancels all steps that are a part of that workflow.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Actions.

    Actions tab in the main repository navigation

  3. In the left sidebar, click the workflow you want to see.

    Workflow list in left sidebar

  4. Under "Workflow runs", click the name of the run you want to see.

    Name of workflow run

  5. In the upper-right corner of the workflow, click Cancel check suite.

    Cancel check suite button

Viewing logs to diagnose failures

If your workflow run fails, you can see which step caused the failure and review the failed step's build logs to troubleshoot. You can see the time it took for each step to run. You can also copy a permalink to a specific line in the log file to share with your team.

GitHub stores full build logs and artifacts for 90 days for pushes and 30 days for pull requests. The retention period for a pull request restarts each time someone pushes to the pull request.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Actions.

    Actions tab in the main repository navigation

  3. In the left sidebar, click the workflow you want to see.

    Workflow list in left sidebar

  4. Under "Workflow runs", click the name of the run you want to see.

    Name of workflow run

  5. In the left sidebar, click the job you want to see.

    List of jobs in left sidebar

  6. To expand the log for a failed step, click the step.

    Failed step name

  7. Optionally, to get a link to a specific line in the logs, click on the step's line number. You can copy the link from the address bar of your web browser.

    Button to copy link

Searching logs

You can search the build logs for a particular step. When you search logs, only expanded steps are included in the results.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Actions.

    Actions tab in the main repository navigation

  3. In the left sidebar, click the workflow you want to see.

    Workflow list in left sidebar

  4. Under "Workflow runs", click the name of the run you want to see.

    Name of workflow run

  5. In the left sidebar, click the job you want to see.

    List of jobs in left sidebar

  6. To expand each step you want to include in your search, click the step.

    Step name

  7. In the upper-right corner of the log output, in the Search logs search box, type a search query.

    Search box to search logs

Downloading logs and artifacts

Artifacts are the files created when you build and test your code. For example, artifacts might include binary or package files, test results, screenshots, or log files. When a run is complete, these files are removed from the virtual environment that ran your workflow and archived for you to download.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Actions.

    Actions tab in the main repository navigation

  3. In the left sidebar, click the workflow you want to see.

    Workflow list in left sidebar

  4. Under "Workflow runs", click the name of the run you want to see.

    Name of workflow run

  5. To download logs, use the Download logs drop-down menu, and select the logs you want to download.

    Download logs drop-down menu

  6. To download artifacts, use the Artifacts drop-down menu, and select the artifact you want to download.

    Artifacts drop-down menu

Enabling debug logging

If the workflow logs do not provide enough detail to diagnose why a workflow, job, or step is not working as expected, you can enable additional debug logging.

These extra logs are controlled by setting secrets in the repository containing the workflow. For more information on setting secrets, see "Creating and using secrets (encrypted variables)."

Enabling runner diagnostic logging

Runner diagnostic logging provides additional log files that contain information about how a runner is executing an action. Two extra log files are added to the log archive:

  • The runner process log, which includes information about coordinating and setting up runners to execute jobs.
  • The worker process log, which logs the execution of a job.
  1. To enable runner diagnostic logging, set the following secret in the repository that contains the workflow: ACTIONS_RUNNER_DEBUG to true.

  2. To download runner diagnostic logs, download the log archive of the workflow run. The runner diagnostic logs are contained in the runner-diagnostic-logs folder. For more information on downloading logs, see "Downloading logs and artifacts."

Enabling step debug logging

Step debug logging increases the verbosity of a job's logs during and after a job's execution.

  1. To enable step debug logging, you must set the following secret in the repository that contains the workflow: ACTIONS_STEP_DEBUG to true.

  2. After setting the secret, more debug events are shown in the step logs. For more information, see "Viewing logs to diagnose failures".

Further reading

Ask a human

Can't find what you're looking for?

Contact us