Skip to content

Latest commit

 

History

History
271 lines (202 loc) · 13.2 KB

README.md

File metadata and controls

271 lines (202 loc) · 13.2 KB
Raw

Hello GitHub Actions

Create a GitHub Action and use it in a workflow.

Welcome

Automation is key for streamlining your work processes, and GitHub Actions is the best way to supercharge your workflow.

  • Who is this for: Developers, DevOps engineers, students, managers, teams, GitHub users.
  • What you'll learn: How to create workflow files, trigger workflows, and find workflow logs.
  • What you'll build: An Actions workflow that will check emoji shortcode references in Markdown files.
  • Prerequisites: In this course you will work with issues and pull requests, as well as edit files. We recommend you take the Introduction to GitHub course first.
  • How long: This course is five steps long and can be finished in less than two hours.

How to start this course

  1. Right-click Start course and open the link in a new tab.
    start-course
  2. In the new tab, follow the prompts to create a new repository.
    • For owner, choose your personal account or an organization to host the repository.
    • We recommend creating a public repository—private repositories will use Actions minutes. Create a new repository
  3. After your new repository is created, wait about 20 seconds, then refresh the page. Follow the step-by-step instructions in the new repository's README.

Step 1: Create a workflow file

Welcome to "Hello GitHub Actions"! 👋

What is GitHub Actions?: GitHub Actions is a flexible way to automate nearly every aspect of your team's software workflow. You can automate testing, continuously deploy, review code, manage issues and pull requests, and much more. The best part, these workflows are stored as code in your repository and easily shared and reused across teams. To learn more, check out these resources:

What is a workflow?: A workflow is a configurable automated process that will run one or more jobs. Workflows are defined in special files in the .github/workflows directory and they execute based on your chosen event. For this exercise, we'll use a pull_request event.

To get you started, we used actions to go ahead and made a branch and pull request for you.

⌨️ Activity: Create a workflow file

  1. Open a new browser tab, and navigate to this same repository. Then, work on the steps in your second tab while you read the instructions in this tab.
  2. Create a pull request to view all the changes you'll make throughout this course. Click the Pull Requests tab, click New pull request, set base: main and compare:welcome-workflow.
  3. Navigate to the Code tab.
  4. From the main branch dropdown, click on the welcome-workflow branch.
  5. Navigate to the .github/workflows/ folder, then select Add file and click on Create new file.
  6. In the Name your file... field, enter welcome.yml.
  7. Add the following content to the welcome.yml file: 
    name: Post welcome comment
on:
  pull_request:
    types: [opened]
permissions:
  pull-requests: write
  8. To commit your changes, click Commit new file.
  9. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.

Step 2: Add a job to your workflow file

Nice work! 🎉 You added a workflow file!

Here's what it means:

  • name: Post welcome comment gives your workflow a name. This name appears on any pull request or in the Actions tab of your repository.
  • on: pull_request: types: [opened] indicates that your workflow will execute anytime a pull request opens in your repository.
  • permissions assigns the workflow permissions to operate on the repository
  • pull-requests: write gives the workflow permission to write to pull requests. This is needed to create the welcome comment.

Next, we need to specify jobs to run.

What is a job?: A job is a set of steps in a workflow that execute on the same runner (a runner is a server that runs your workflows when triggered). Workflows have jobs, and jobs have steps. Steps are executed in order and are dependent on each other. We'll add steps in the next step of this exercise. To read more about jobs, see "Jobs".

In this step of our exercise, we will add a "build" job. We will specify ubuntu-latest as the fastest and cheapest job runner available. If you want to read more about why we'll use that runner, see the code explanation for the line runs-on: ubuntu-latest in the "Understanding the workflow file" article.

⌨️ Activity: Add a job to your workflow file

  1. Open your welcome.yml file.
  2. Update the contents of the file to: 
    name: Post welcome comment
on:
  pull_request:
    types: [opened]
permissions:
  pull-requests: write
jobs:
  build:
    name: Post welcome comment
    runs-on: ubuntu-latest
  3. Click Start commit in the top right of the workflow editor.
  4. Type your commit message and commit your changes directly to your branch.
  5. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.

Step 3: Add actions to your workflow file

Nice work adding a job to your workflow! 💃

Workflows have jobs, and jobs have steps. So now we'll add steps to your workflow.

What are steps?: Actions steps will run during our job in order. Each step is either a shell script that will be executed, or an action that will be run. Each step must pass for the next step to run. Actions steps can be used from within the same repository, from any other public repository, or from a published Docker container image.

In our action, we post a comment on the pull request using a bash script and GitHub CLI.

⌨️ Activity: Add Actions steps to your workflow file

  1. Open your welcome.yml file.
  2. Update the contents of the file to: 
    name: Post welcome comment
on:
  pull_request:
    types: [opened]
permissions:
  pull-requests: write
jobs:
  build:
    name: Post welcome comment
    runs-on: ubuntu-latest
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_URL: ${{ github.event.pull_request.html_url }}
  3. Click Start commit in the top right of the workflow editor.
  4. Type your commit message and commit your changes directly to your branch.
  5. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.

Step 4: Merge your workflow file

You're now able to write and run an Actions workflow! ✨

Merge your changes so the action will be a part of the main branch.

⌨️ Activity: Merge your workflow file

  1. In your repo, click on the Pull requests tab.
  2. Click on the pull request you created in step 1.
  3. Click Merge pull request, then click Confirm merge.
  4. Optionally, click Delete branch to delete your welcome-workflow branch.
  5. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.

Step 5: Trigger the workflow

You've now got a fully functioning workflow! 😄

Your new action will run any time a pull request has been opened.

Seeing your action in action: The status of your action is shown in a pull request before you merge, look for All checks have passed when you try out the steps below. You can also view them from the Actions tab in your repository. From there, you will see all the actions that have run, and you can click on each action to view details and access log files.

View an action's log

⌨️ Activity: Trigger the workflow

  1. Make a new branch named test-workflow.
  2. Commit any change to your branch, such as adding an emoji to your README.md file.
  3. Create the pull request on your branch.
  4. See your action run on your pull request.
  5. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.

Finish

Congratulations friend, you've completed this course!

celebrate

Here's a recap of all the tasks you've accomplished in your repository:

  • You've created your first GitHub Actions workflow file.
  • You learned where to make your workflow file.
  • You created an event trigger, a job, and steps for your workflow.
  • You're ready to automate anything you can dream of.

What's next?

Get help: Post in our discussion board • Review the GitHub status page

© 2022 GitHub • Code of Conduct • CC-BY-4.0 License