Skip to content

Commit

Permalink
Add "About workflows" article (github#26520)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lucascosti
lucascosti authored Apr 22, 2022
1 parent 44bcce5 commit c126eed
Show file tree
Hide file tree
Showing 10 changed files with 263 additions and 230 deletions.
Binary file added assets/images/help/settings/actions-create-starter-workflow-updated-ui.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
177 changes: 5 additions & 172 deletions content/actions/learn-github-actions/understanding-github-actions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,7 @@ You can configure a {% data variables.product.prodname_actions %} _workflow_ to

### Workflows

A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.

You can have multiple workflows in a repository, each of which can perform a different set of steps. For example, you can have one workflow to build and test pull requests, another workflow to deploy your application every time a release is created, and still another workflow that adds a label every time someone opens a new issue.
{% data reusables.actions.about-workflows-long %}

{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %}You can reference a workflow within another workflow, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."{% endif %}

Expand Down Expand Up @@ -86,173 +84,7 @@ For more information, see "[Creating actions](/actions/creating-actions)."

{% data reusables.actions.about-runners %} Each runner can run a single job at a time. {% ifversion ghes or ghae %} You must host your own runners for {% data variables.product.product_name %}. {% elsif fpt or ghec %}{% data variables.product.company_short %} provides Ubuntu Linux, Microsoft Windows, and macOS runners to run your workflows; each workflow run executes in a fresh, newly-provisioned virtual machine. If you need a different operating system or require a specific hardware configuration, you can host your own runners.{% endif %} For more information{% ifversion fpt or ghec %} about self-hosted runners{% endif %}, see "[Hosting your own runners](/actions/hosting-your-own-runners)."

## Create an example workflow

{% data variables.product.prodname_actions %} uses YAML syntax to define the workflow. Each workflow is stored as a separate YAML file in your code repository, in a directory called `.github/workflows`.

You can create an example workflow in your repository that automatically triggers a series of commands whenever code is pushed. In this workflow, {% data variables.product.prodname_actions %} checks out the pushed code, installs the software dependencies, and runs `bats -v`.

1. In your repository, create the `.github/workflows/` directory to store your workflow files.
1. In the `.github/workflows/` directory, create a new file called `learn-github-actions.yml` and add the following code.

```yaml
name: learn-github-actions
on: [push]
jobs:
check-bats-version:
runs-on: ubuntu-latest
steps:
- uses: {% data reusables.actions.action-checkout %}
- uses: {% data reusables.actions.action-setup-node %}
with:
node-version: '14'
- run: npm install -g bats
- run: bats -v
```
1. Commit these changes and push them to your {% data variables.product.prodname_dotcom %} repository.
Your new {% data variables.product.prodname_actions %} workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. For details about a workflow's execution history, see "[Viewing the workflow's activity](/actions/learn-github-actions/introduction-to-github-actions#viewing-the-workflows-activity)."
## Understanding the workflow file
To help you understand how YAML syntax is used to create a workflow file, this section explains each line of the introduction's example:
<table>
<tr>
<td>
```yaml
name: learn-github-actions
```
</td>
<td>
<em>Optional</em> - The name of the workflow as it will appear in the Actions tab of the {% data variables.product.prodname_dotcom %} repository.
</td>
</tr>
<tr>
<td>
```yaml
on: [push]
```
</td>
<td>
Specifies the trigger for this workflow. This example uses the <code>push</code> event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see <a href="https://docs.github.com/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore">"Workflow syntax for {% data variables.product.prodname_actions %}."</a>
</td>
</tr>
<tr>
<td>
```yaml
jobs:
```
</td>
<td>
Groups together all the jobs that run in the <code>learn-github-actions</code> workflow.
</td>
</tr>
<tr>
<td>
```yaml
check-bats-version:
```
</td>
<td>
Defines a job named <code>check-bats-version</code>. The child keys will define properties of the job.
</td>
</tr>
<tr>
<td>
```yaml
runs-on: ubuntu-latest
```
</td>
<td>
Configures the job to run on the latest version of an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see <a href="https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on">"Workflow syntax for {% data variables.product.prodname_actions %}."</a>
</td>
</tr>
<tr>
<td>
```yaml
steps:
```
</td>
<td>
Groups together all the steps that run in the <code>check-bats-version</code> job. Each item nested under this section is a separate action or shell script.
</td>
</tr>
<tr>
<td>
```yaml
- uses: {% data reusables.actions.action-checkout %}
```
</td>
<td>
The <code>uses</code> keyword specifies that this step will run <code>v3</code> of the <code>actions/checkout</code> action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will run against the repository's code.
</td>
</tr>
<tr>
<td>
```yaml
- uses: {% data reusables.actions.action-setup-node %}
with:
node-version: '14'
```
</td>
<td>
This step uses the <code>{% data reusables.actions.action-setup-node %}</code> action to install the specified version of the Node.js (this example uses v14). This puts both the <code>node</code> and <code>npm</code> commands in your <code>PATH</code>.
</td>
</tr>
<tr>
<td>
```yaml
- run: npm install -g bats
```
</td>
<td>
The <code>run</code> keyword tells the job to execute a command on the runner. In this case, you are using <code>npm</code> to install the <code>bats</code> software testing package.
</td>
</tr>
<tr>
<td>
```yaml
- run: bats -v
```
</td>
<td>
Finally, you'll run the <code>bats</code> command with a parameter that outputs the software version.
</td>
</tr>
</table>
### Visualizing the workflow file
In this diagram, you can see the workflow file you just created and how the {% data variables.product.prodname_actions %} components are organized in a hierarchy. Each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts. To find more prebuilt actions for your workflows, see "[Finding and customizing actions](/actions/learn-github-actions/finding-and-customizing-actions)."
![Workflow overview](/assets/images/help/images/overview-actions-event.png)
## Viewing the workflow's activity
Once your workflow has started running, you can see a visualization graph of the run's progress and view each step's activity on {% data variables.product.prodname_dotcom %}.
{% data reusables.repositories.navigate-to-repo %}
1. Under your repository name, click **Actions**.
![Navigate to repository](/assets/images/help/images/learn-github-actions-repository.png)
1. In the left sidebar, click the workflow you want to see.
![Screenshot of workflow results](/assets/images/help/images/learn-github-actions-workflow.png)
1. Under "Workflow runs", click the name of the run you want to see.
![Screenshot of workflow runs](/assets/images/help/images/learn-github-actions-run.png)
1. Under **Jobs** or in the visualization graph, click the job you want to see.
![Select job](/assets/images/help/images/overview-actions-result-navigate.png)
1. View the results of each step.
![Screenshot of workflow run details](/assets/images/help/images/overview-actions-result-updated-2.png)
{% data reusables.actions.workflow-basic-example-and-explanation %}

## Next steps

Expand All @@ -268,7 +100,8 @@ To understand how billing works for {% data variables.product.prodname_actions %

{% data reusables.actions.contacting-support %}

{% ifversion ghec or ghes or ghae %}
## Further reading

{% ifversion ghec or ghes or ghae %}
- "[About {% data variables.product.prodname_actions %} for enterprises](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises)"{% endif %}
- "[About {% data variables.product.prodname_actions %} for enterprises](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises)"
{% endif %}
Loading

0 comments on commit c126eed

Please sign in to comment.