Moving to GitHub Actions from Travis

GitHub Actions execute faster and more reliably than Travis jobs, so we are converting existing repositories to use them. This document describes how to accomplish this transition for existing packages. New packages should start with GitHub Actions by default; additional customizations that may be useful are suggested in the new package documentation.

Note: you must have administrator rights to the repository to follow this procedure.

Travis uses a .travis.yml file that specifies the workflow to be executed when events such as pushes or pull requests occur for the repository. GitHub Actions use .github/workflows/*.yaml files instead. These workflows execute in parallel. Migrating a package consists of replacing the .travis.yml file with one or more appropriate GitHub Actions workflows files.

If the .travis.yml file contains only the default execution of flake8 for Python “lint” checking, this can be done entirely in the GitHub web interface, or it can be done a bit more cleanly from the command line.

If your .travis.yml does more than run flake8, please consult an expert for assistance.

GitHub web interface

  1. Go to the repository you are transitioning at https://github.com/lsst/{repo}.

  2. Go to the “Settings” page of the repository. This may be under the right-side “…” menu depending on your window width.

  3. Choose “Branches” in the left sidebar.

  4. Under “Branch protection rules”, click “Edit” next to branch “main”.

  5. Under “Require branches to be up to date before merging”, uncheck any status checks that contain “travis-ci”.

  6. Click “Save changes” at the bottom of the page.

  7. Go back to the “Code” page and select .travis.yml.

  8. Select the “trash can” icon to delete this file.

  9. Add a commit comment such as “Remove Travis workflow.” and choose a branch name. This branch name doesn’t need to follow our tickets/ convention; a name like u/{user}/remove-travis is adequate.

  10. Commit the change, create a pull request, and merge it.

  11. Go to the “Actions” page (between “Pull Requests” and “Projects” at the top of the GitHub page).

  12. Choose the “LSST DM Python lint Workflow” and click on “Set up this workflow”.

  13. Choose “Start commit”.

  14. Add a commit comment such as “Add Python lint workflow.” and choose a branch name. Again, something like u/{user}/add-lint-workflow is sufficient as a branch name.

  15. Commit the change, create a pull request, and merge it.

  16. Go back to the “Settings” page, “Branches”, “Branch protection rules”, and “Edit” next to branch “main”.

  17. Under “Require branches to be up to date before merging”, check the new “lint” checkbox.

  18. Click “Save changes” at the bottom of the page.

  19. If you like, you may choose “Webhooks” in the left sidebar and delete the https://notify.travis-ci.org/ entry, but it does no harm to leave it.

Command line

  1. Clone the repository you are transitioning from git@github.com:lsst/{repo}.

  2. Create a branch: git checkout -b u/{user}/migrate-to-gha

  3. git rm .travis.yml

  4. mkdir -p .github/workflows; cd .github/workflows

  5. curl -LO https://raw.githubusercontent.com/lsst/.github/main/workflow-templates/lint.yaml

  6. git add lint.yaml

  7. git commit and add a commit message such as “Migrate from Travis to GitHub Actions.”

  8. git push -u origin u/{user}/migrate-to-gha

  9. Create a pull request from your branch.

  10. Go to the “Settings” page of the repository. This may be under the right-side “…” menu depending on your window width.

  11. Choose “Branches” in the left sidebar.

  12. Under “Branch protection rules”, click “Edit” next to branch “main”.

  13. Under “Require branches to be up to date before merging”, uncheck any status checks that contain “travis-ci”. Check any other status checks, in particular lint.

  14. Click “Save changes” at the bottom of the page.

  15. Merge your pull request.

  16. If you like, you may choose “Webhooks” in the left sidebar and delete the https://notify.travis-ci.org/ entry, but it does no harm to leave it.

Further reading