--- obj: concept website: https://github.com/features/actions --- # GitHub Actions GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. GitHub Actions goes beyond just DevOps and lets you run workflows when other events happen in your repository. For example, you can run a workflow to automatically add the appropriate labels whenever someone creates a new issue in your repository. You can configure a GitHub Actions _workflow_ to be triggered when an _event_ occurs in your repository, such as a pull request being opened or an issue being created. Your workflow contains one or more _jobs_ which can run in sequential order or in parallel. Each job will run inside its own virtual machine _runner_, or inside a container, and has one or more _steps_ that either run a script that you define or run an _action_, which is a reusable extension that can simplify your workflow. Example: ```yml name: Rust on: push: pull_request: env: CARGO_TERM_COLOR: always jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Build run: cargo build --verbose - name: Run tests run: cargo test --verbose ``` ## Expressions You can use expressions to programmatically set [environment variables](../linux/Environment%20Variables.md) in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators. Expressions are commonly used with the conditional `if` keyword in a workflow file to determine whether a step should run. When an `if` conditional is `true`, the step will run. You need to use specific syntax to tell [GitHub](../applications/development/GitHub.md) to evaluate an expression rather than treat it as a string. `${{ }}` Secrets passed to GitHub Actions can be used: `${{ secrets.MYSECRET }}` ### Functions #### contains `contains( search, item )` Returns `true` if `search` contains `item`. If `search` is an array, this function returns `true` if the `item` is an element in the array. If `search` is a string, this function returns `true` if the `item` is a substring of `search`. This function is not case sensitive. Casts values to a string. #### startsWith `startsWith( searchString, searchValue )` Returns `true` when `searchString` starts with `searchValue`. This function is not case sensitive. Casts values to a string. #### endsWith `endsWith( searchString, searchValue )` Returns `true` if `searchString` ends with `searchValue`. This function is not case sensitive. Casts values to a string. #### format `format( string, replaceValue0, replaceValue1, ..., replaceValueN)` Replaces values in the `string`, with the variable `replaceValueN`. Variables in the `string` are specified using the `{N}` syntax, where `N` is an integer. You must specify at least one `replaceValue` and `string`. There is no maximum for the number of variables (`replaceValueN`) you can use. Escape curly braces using double braces. #### always Causes the step to always execute, and returns `true`, even when canceled. The `always` expression is best used at the step level or on tasks that you expect to run even when a job is canceled. For example, you can use `always` to send logs even when a job is canceled. Example of `always`: ```yaml if: ${{ always() }} ``` #### failure Returns `true` when any previous step of a job fails. If you have a chain of dependent jobs, `failure()` returns `true` if any ancestor job fails. Example of `failure`: ```yaml steps: ... - name: The job has failed if: ${{ failure() }} ``` ## Workflows A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a [YAML](../files/YAML.md) 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. Workflows are defined in the `.github/workflows` directory in a repository, and a repository can have multiple workflows, each of which can perform a different set of tasks. 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. ### Syntax #### `name` The name of the workflow. [GitHub](../applications/development/GitHub.md) displays the names of your workflows under your repository's "Actions" tab. If you omit `name`, [GitHub](../applications/development/GitHub.md) displays the workflow file path relative to the root of the repository. #### `on` To automatically trigger a workflow, use `on` to define which events can cause the workflow to run. You can define single or multiple events that can trigger a workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. These options are described in the following sections. **Using a single event:** For example, a workflow with the following `on` value will run when a push is made to any branch in the workflow's repository: ```yaml on: push ``` **Using multiple events:** You can specify a single event or multiple events. For example, a workflow with the following `on` value will run when a push is made to any branch in the repository or when someone forks the repository: ```yaml on: [push, fork] ``` If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered. **Using activity types:** Some events have activity types that give you more control over when your workflow should run. Use `on..types` to define the type of event activity that will trigger a workflow run. For example, the `issue_comment` event has the `created`, `edited`, and `deleted` activity types. If your workflow triggers on the `label` event, it will run whenever a label is created, edited, or deleted. If you specify the `created` activity type for the `label` event, your workflow will run when a label is created but not when a label is edited or deleted. ```yaml on: label: types: - created ``` If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events. ```yaml on: issues: types: - opened - labeled ``` **Using filters:** Some events have filters that give you more control over when your workflow should run. For example, the `push` event has a `branches` filter that causes your workflow to run only when a push to a branch that matches the `branches` filter occurs, instead of when any push occurs. ```yaml on: push: branches: - main - 'releases/**' ``` #### `on..types` Use `on..types` to define the type of activity that will trigger a workflow run. Most [GitHub](../applications/development/GitHub.md) events are triggered by more than one type of activity. For example, the `label` is triggered when a label is `created`, `edited`, or `deleted`. The `types` keyword enables you to narrow down activity that causes the workflow to run. When only one activity type triggers a [webhook](../internet/Webhook.md) event, the `types` keyword is unnecessary. ```yaml on: label: types: [created, edited] ``` #### `on.schedule` You can use `on.schedule` to define a time schedule for your workflows. You can schedule a workflow to run at specific UTC times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes. This example triggers the workflow every day at 5:30 and 17:30 UTC: ```yaml on: schedule: # * is a special character in YAML so you have to quote this string - cron: '30 5,17 * * *' ``` A single workflow can be triggered by multiple `schedule` events. You can access the schedule event that triggered the workflow through the `github.event.schedule` context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the `Not on Monday or Wednesday` step on Monday and Wednesday. ```yaml on: schedule: - cron: '30 5 * * 1,3' - cron: '30 5 * * 2,4' jobs: test_schedule: runs-on: ubuntu-latest steps: - name: Not on Monday or Wednesday if: github.event.schedule != '30 5 * * 1,3' run: echo "This step will be skipped on Monday and Wednesday" - name: Every time run: echo "This step will always run" ``` #### `on.workflow_dispatch` When using the `workflow_dispatch` event, you can manually run this workflow from the UI. #### `env` A `map` of variables that are available to the steps of all jobs in the workflow. You can also set variables that are only available to the steps of a single job or to a single step. For more information, see `jobs..env` and `jobs..steps[*].env`. Variables in the `env` map cannot be defined in terms of other variables in the map. **Example of `env`:** ```yaml env: SERVER: production ``` #### `jobs` A workflow run is made up of one or more `jobs`, which run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the `jobs..needs` keyword. Each job runs in a runner environment specified by `runs-on`. ##### `jobs.` Use `jobs.` to give your job a unique identifier. The key `job_id` is a string and its value is a map of the job's configuration data. You must replace `` with a string that is unique to the `jobs` object. The `` must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. Use `jobs..name` to set a name for the job, which is displayed in the [GitHub](../applications/development/GitHub.md) UI. **Example: Creating jobs:** In this example, two jobs have been created, and their `job_id` values are `my_first_job` and `my_second_job`. ```yaml jobs: my_first_job: name: My first job my_second_job: name: My second job ``` ##### `jobs..container` Use `jobs..container` to create a container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts. If you do not set a `container`, all steps will run directly on the host specified by `runs-on` unless a step refers to an action configured to run in a container. **Example: Running a job within a container:** ```yaml name: CI on: push: branches: [ main ] jobs: container-test-job: runs-on: ubuntu-latest container: image: node:18 env: NODE_ENV: development ports: - 80 volumes: - my_docker_volume:/volume_mount options: --cpus 1 steps: - name: Check for dockerenv file run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv) ``` When you only specify a container image, you can omit the `image` keyword. ```yaml jobs: container-test-job: runs-on: ubuntu-latest container: node:18 ``` ##### `jobs..needs` Use `jobs..needs` to identify any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails or is skipped, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue. If a run contains a series of jobs that need each other, a failure or skip applies to all jobs in the dependency chain from the point of failure or skip onwards. If you would like a job to run even if a job it is dependent on did not succeed, use the `always()` conditional expression in `jobs..if`. **Example: Requiring successful dependent jobs:** ```yaml jobs: job1: job2: needs: job1 job3: needs: [job1, job2] ``` ##### `jobs..if` You can use the `jobs..if` conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional. When you use expressions in an `if` conditional, you can, optionally, omit the `${{ }}` expression syntax because GitHub Actions automatically evaluates the `if` conditional as an expression. However, this exception does not apply everywhere. You must always use the `${{ }}` expression syntax or escape with `''`, `""`, or `()` when the expression starts with `!`, since `!` is reserved notation in [YAML](../files/YAML.md) format. For example: ```yaml if: ${{ ! startsWith(github.ref, 'refs/tags/') }} ``` For more information, see "Expressions." ##### `jobs..runs-on` Use `jobs..runs-on` to define the type of machine to run the job on. ##### `jobs..env` A `map` of variables that are available to all steps in the job. You can set variables for the entire workflow or an individual step. ##### `jobs..steps` A job contains a sequence of tasks called `steps`. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a [Docker](../tools/Docker.md) registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to [environment variables](../linux/Environment%20Variables.md) are not preserved between steps. [GitHub](../applications/development/GitHub.md) provides built-in steps to set up and complete a job. **Example of `jobs..steps`:** ```yaml name: Greeting from Mona on: push jobs: my-job: name: My Job runs-on: ubuntu-latest steps: - name: Print a greeting env: MY_VAR: Hi there! My name is FIRST_NAME: Mona MIDDLE_NAME: The LAST_NAME: Octocat run: | echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME. ``` - `jobs..steps[*].if` You can use the `if` conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional. - `jobs..steps[*].name` A name for your step to display on [GitHub](../applications/development/GitHub.md). - `jobs..steps[*].uses` Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published [Docker](../tools/Docker.md) container image. Some actions require inputs that you must set using the `with` keyword. Review the action's README file to determine the inputs required. **Example: Using versioned actions** ```yaml steps: # Reference a specific commit - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # Reference the major version of a release - uses: actions/checkout@v4 # Reference a specific version - uses: actions/checkout@v4.2.0 # Reference a branch - uses: actions/checkout@main ``` - `jobs..steps[*].run` Runs command-line programs using the operating system's [shell](../applications/cli/Shell.md). If you do not provide a `name`, the step name will default to the text specified in the `run` command. Commands run using non-login shells by default. Each `run` keyword represents a new process and [shell](../applications/cli/Shell.md) in the runner environment. When you provide multi-line commands, each line runs in the same [shell](../applications/cli/Shell.md). For example: A single-line command: ```yaml - name: Install Dependencies run: npm install ``` A multi-line command: ```yaml - name: Clean install dependencies and build run: | npm ci npm run build ``` - `jobs..steps[*].working-directory` Using the `working-directory` keyword, you can specify the working directory of where to run the command. ```yaml - name: Clean temp directory run: rm -rf * working-directory: ./temp ``` - `jobs..steps[*].with` A `map` of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as [environment variables](../linux/Environment%20Variables.md). The variable is prefixed with `INPUT_` and converted to upper case. Input parameters defined for a [Docker](../tools/Docker.md) container must use `args`. For more information, see "`jobs..steps[*].with.args`." **Example of `jobs..steps[*].with` Defines the three input parameters (`first_name`, `middle_name`, and `last_name`) defined by the `hello_world` action. These input variables will be accessible to the `hello-world` action as `INPUT_FIRST_NAME`, `INPUT_MIDDLE_NAME`, and `INPUT_LAST_NAME` [environment variables](../linux/Environment%20Variables.md). ```yaml jobs: my_first_job: steps: - name: My first step uses: actions/hello_world@main with: first_name: Mona middle_name: The last_name: Octocat ``` - `jobs..steps[*].with.args` A `string` that defines the inputs for a [Docker](../tools/Docker.md) container. [GitHub](../applications/development/GitHub.md) passes the `args` to the container's `ENTRYPOINT` when the container starts up. An `array of strings` is not supported by this parameter. A single argument that includes spaces should be surrounded by double quotes `""`. - `jobs..steps[*].env` Sets variables for steps to use in the runner environment. You can also set variables for the entire workflow or a job. For more information, see `env` and `jobs..env`. When more than one environment variable is defined with the same name, [GitHub](../applications/development/GitHub.md) uses the most specific variable. For example, an environment variable defined in a step will override job and workflow [environment variables](../linux/Environment%20Variables.md) with the same name, while the step executes. An environment variable defined for a job will override a workflow variable with the same name, while the job executes. Public actions may specify expected variables in the README file. If you are setting a secret or sensitive value, such as a password or token, you must set secrets using the `secrets` context. **Example of `jobs..steps[*].env`** ```yaml steps: - name: My first action env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} FIRST_NAME: Mona LAST_NAME: Octocat ``` ## Events An event is a specific activity in a repository that triggers a workflow run. For example, activity can originate from [GitHub](../applications/development/GitHub.md) when someone creates a pull request, opens an issue, or pushes a commit to a repository. You can also trigger a workflow to run on a schedule, by posting to a REST API, or manually. ### `create` Runs your workflow when someone creates a [Git](Git.md) reference ([Git](Git.md) branch or tag) in the workflow's repository. For example, you can run a workflow when the `create` event occurs. ```yaml on: create ``` ### `delete` Runs your workflow when someone deletes a [Git](Git.md) reference ([Git](Git.md) branch or tag) in the workflow's repository. For example, you can run a workflow when the `delete` event occurs. ```yaml on: delete ``` ### `discussion` Runs your workflow when a discussion in the workflow's repository is created or modified. Activity Types: - `created` - `edited` - `deleted` - `transferred` - `pinned` - `unpinned` - `labeled` - `unlabeled` - `locked` - `unlocked` - `category_changed` - `answered` - `unanswered` For example, you can run a workflow when a discussion has been `created`, `edited`, or `answered`. ```yaml on: discussion: types: [created, edited, answered] ``` ### `discussion_comment` Runs your workflow when a comment on a discussion in the workflow's repository is created or modified. Activity Types: - `created` - `edited` - `deleted` For example, you can run a workflow when a discussion comment has been `created` or `deleted`. ```yaml on: discussion_comment: types: [created, deleted] ``` ### `fork` Runs your workflow when someone forks a repository. For example, you can run a workflow when the `fork` event occurs. ```yaml on: fork ``` ### `issue_comment` Runs your workflow when an issue or pull request comment is created, edited, or deleted. Activity Types: - `created` - `edited` - `deleted` For example, you can run a workflow when an issue or pull request comment has been `created` or `deleted`. ```yaml on: issue_comment: types: [created, deleted] ``` ### `issues` Runs your workflow when an issue in the workflow's repository is created or modified. Activity Types: - `opened` - `edited` - `deleted` - `transferred` - `pinned` - `unpinned` - `closed` - `reopened` - `assigned` - `unassigned` - `labeled` - `unlabeled` - `locked` - `unlocked` - `milestoned` - `demilestoned` For example, you can run a workflow when an issue has been `opened`, `edited`, or `milestoned`. ```yaml on: issues: types: [opened, edited, milestoned] ``` ### `milestone` Runs your workflow when a milestone in the workflow's repository is created or modified. Activity Types: - `created` - `closed` - `opened` - `edited` - `deleted` For example, you can run a workflow when a milestone has been `opened` or `deleted`. ```yaml on: milestone: types: [opened, deleted] ``` ### `pull_request` Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated. Activity Types: - `assigned` - `unassigned` - `labeled` - `unlabeled` - `opened` - `edited` - `closed` - `reopened` - `synchronize` - `converted_to_draft` - `ready_for_review` - `locked` - `unlocked` - `milestoned` - `demilestoned` - `review_requested` - `review_request_removed` - `auto_merge_enabled` - `auto_merge_disabled` For example, you can run a workflow when a pull request has been opened or reopened. ```yaml on: pull_request: types: [opened, reopened] ``` ### `push` Runs your workflow when you push a commit or tag, or when you create a repository from a template. You can use the `branches` or `branches-ignore` filter to configure your workflow to only run when specific branches are pushed. You can use the `tags` or `tags-ignore` filter to configure your workflow to only run when specific tags are pushed. If you use both the `branches` filter and the `paths` filter, the workflow will only run when both filters are satisfied. For example, the following workflow will only run when a push that includes a change to a JavaScript (`.js`) file is made to a branch whose name starts with `releases/`: ```yaml on: push: branches: - 'releases/**' paths: - '**.js' ``` For example, you can run a workflow when the `push` event occurs. ```yaml on: push ``` ### `release` Runs your workflow when release activity in your repository occurs. Activity Types: - `published` - `unpublished` - `created` - `edited` - `deleted` - `prereleased` - `released` For example, you can run a workflow when a release has been `published`. ```yaml on: release: types: [published] ``` ### `schedule` The `schedule` event allows you to trigger a workflow at a scheduled time. You can schedule a workflow to run at specific UTC times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes. A single workflow can be triggered by multiple `schedule` events. You can access the schedule event that triggered the workflow through the `github.event.schedule` context. This example triggers the workflow every day at 5:30 and 17:30 UTC: ```yaml on: schedule: # * is a special character in YAML so you have to quote this string - cron: '30 5,17 * * *' ``` ### `workflow_dispatch` To enable a workflow to be triggered manually, you need to configure the `workflow_dispatch` event. You can manually trigger a workflow run using the [GitHub](../applications/development/GitHub.md) API, [GitHub](../applications/development/GitHub.md) CLI, or [GitHub](../applications/development/GitHub.md) browser interface. ```yaml on: workflow_dispatch ``` ## Jobs A job is a set of _steps_ in a workflow that is executed on the same runner. Each step is either a [shell](../applications/cli/Shell.md) script that will be executed, or an _action_ that will be run. Steps are executed in order and are dependent on each other. Since each step is executed on the same runner, you can share data from one step to another. For example, you can have a step that builds your application followed by a step that tests the application that was built. You can configure a job's dependencies with other jobs; by default, jobs have no dependencies and run in parallel with each other. When a job takes a dependency on another job, it will wait for the dependent job to complete before it can run. For example, you may have multiple build jobs for different architectures that have no dependencies, and a packaging job that is dependent on those jobs. The build jobs will run in parallel, and when they have all completed successfully, the packaging job will run. ## Actions An _action_ is a custom application for the GitHub Actions platform that performs a complex but frequently repeated task. Use an action to help reduce the amount of repetitive code that you write in your workflow files. An action can pull your [git](Git.md) repository from [GitHub](../applications/development/GitHub.md), set up the correct toolchain for your build environment, or set up the authentication to your cloud provider. You can write your own actions, or you can find actions to use in your workflows in the GitHub Marketplace.