GitHub announced the release into public beta of their Actions API. The Actions API can be used to manage GitHub Actions via a REST API. Endpoints available within the API allow for managing artifacts, secrets, runners, and workflows.
GitHub Actions allow for automating workflows based on repository events such as push, issue creation, or the creation of a new release. These workflows can be created either via a visual editor or by writing YAML code. GitHub released CI/CD for GitHub Actions in August allowing for building and deploying software directly within GitHub and without the need for third-party services.
The workflows API allows for viewing workflows associated with a repository. This includes listing all the workflows or getting a specific workflow. For example, the request:
curl -u username:token \
"https://api.github.com/repos/my-org/hello-world/actions/workflows/72844"
Will return the following details about workflow 72844 within the hello-world repo:
{
"id": 72844,
"node_id": "MDg6V29ya2Zsb3cxNjEzMzU=",
"name": "CI",
"path": ".github/workflows/blank.yml",
"state": "active",
"created_at": "2020-01-08T23:48:37.000-08:00",
"updated_at": "2020-01-08T23:50:21.000-08:00",
"url": "https://api.github.com/repos/my-org/hello-world/actions/workflows/72844",
"html_url": "https://github.com/my-org/hello-world/blob/master/.github/workflows/72844",
"badge_url": "https://github.com/my-org/hello-world/workflows/CI/badge.svg"
}
Details from a run of a workflow can be accessed through the workflow runs API. A Workflow run within GitHub Actions is an instance of a workflow that runs on the configured event. This API provides access to view runs, review the logs for a run, re-trigger a workflow, and cancel active runs. These endpoints provide access to the status of the runs including the overall outcome and duration. The Workflow jobs API enables access to details about the jobs including log files.
The API route for accessing the workflow run logs provides a redirect URL to download an archive of the log files. This link is accessible to anyone with read access to the repository and expires after one minute. This URL is provided as the location header in the response. As an example, it could be downloaded via one request with CURL by enabling the verbose output to see the header and using -L to permit the redirection to the location value:
curl -v -L -u username:token -o logs.zip /
"https://api.github.com/repos/my-org/my-repo/actions/runs/30209828/logs"
With the artifacts API users are able to download, delete, and retrieve information about workflow artifacts. Artifacts allow for sharing data between jobs in a workflow and also for persisting data after a workflow finishes.
While GitHub Actions run within Docker containers on GitHub's servers by default, there is also support for self-hosted runners. Self-hosted runners allow for executing workflows on servers hosted within your own environment. The Self-hosted runners API allows for listing the runners within a repository, getting a specific runner, removing a runner, and creating the appropriate tokens for authorizing the runner. With this it is now possible to automate the the creation and clean-up of runners.
To facilitate working with the new API endpoints, GitHub has added additional data to the runner context. Each Actions run now includes a run_id and run_number. These values can be integrated into workflow scripts to more easily interact with the new API endpoints.
The Actions API is available for authenticated users, OAuth Apps, and GitHub Apps. Access tokens will require repo scope on private repositories and public_repo scope on public repositories.
The GitHub Actions API is available to all users who currently have access to GitHub Actions. GitHub Actions is available with most of GitHub's pricing plans. However, Actions is not available for repositories owned by accounts that are using the legacy per-repo plans. While the API is in beta, GitHub will be posting changes to their blog based on developer feedback.