Merge pull request #41 from xebia/5.1-Manage-your-work-with-GitHub-projects-v2

5.1 manage your work with GitHub projects v2

Author: Chukslord1

learn-pr/github/github-actions-automate-tasks/1-introduction.yml

@@ -4,7 +4,7 @@ title: Introduction
 metadata:
   title: Introduction
   description: An introduction to GitHub Actions and workflows.
-  ms.date: 10/08/2024
+  ms.date: 05/01/2025
   author: juliakm
   ms.author: jukullam
   ms.topic: unit

learn-pr/github/github-actions-automate-tasks/includes/2-github-actions-automate-development-tasks.md

@@ -156,6 +156,56 @@ The last part of this workflow file sets the `MY_NAME` variable value for this w
 
 For more information on workflow syntax, see [Workflow syntax for GitHub Actions](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions?azure-portal=true)
 
+## Referencing Actions in Workflows
+
+When creating workflows in GitHub Actions, you can reference actions from various sources. These actions can be used to automate tasks in your workflows. Below are the primary sources where workflows can reference actions:
+
+1. **A published Docker container image on Docker Hub**  
+   Workflows can reference actions that are published as Docker container images on Docker Hub. These actions are containerized and include all dependencies required to execute the action. To use such an action, you specify the Docker image in the `uses` attribute of your workflow step. For example:
+   ```yml
+   steps:
+     - name: Run a Docker action
+       uses: docker://<docker-image-name>:<tag>
+   ```
+
+2. **Any public repository**  
+   Actions hosted in public repositories can be directly referenced in your workflows. These actions are accessible to anyone and can be used by specifying the repository name and version (Git ref, SHA, or tag) in the `uses` attribute. For example:
+   ```yml
+   steps:
+     - name: Use a public action
+       uses: actions/checkout@v3
+   ```
+
+[!IMPORTANT]
+> **For better security, use a full commit SHA when referencing actions—not just a tag like `@v3`.**  
+> This makes sure your workflow always uses the exact same code, even if the action is updated or changed later.  
+> Example: `uses: actions/checkout@c2c1744e079e0dd11c8e0af4a96064ca4f6a2e9e`
+
+3. **The same repository as your workflow file**  
+   You can reference actions stored in the same repository as your workflow file. This is useful for custom actions that are specific to your project. To reference such actions, use a relative path to the action's directory. For example:
+   ```yml
+   steps:
+     - name: Use a local action
+       uses: ./path-to-action
+   ```
+
+For more details, see [security hardening guidance for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions).
+
+4. **An enterprise marketplace**  
+   If your organization uses GitHub Enterprise, you can reference actions from your enterprise's private marketplace. These actions are curated and managed by your organization, ensuring compliance with internal standards. For example:
+   ```yml
+   steps:
+     - name: Use an enterprise marketplace action
+       uses: enterprise-org/action-name@v1
+   ```
+
+### Additional Notes
+- Actions in private repositories can also be referenced, but they require proper authentication and permissions.
+- When referencing actions, always specify a version (Git ref, SHA, or tag) to ensure consistency and avoid unexpected changes.
+
+For more information, see [Referencing actions in workflows](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions).
+
+
 ## GitHub-hosted versus self-hosted runners
 
 We briefly mentioned runners as being associated with a job. A runner is simply a server that has the GitHub Actions runner application installed. In the previous workflow example, there was a `runs-on: ubuntu-latest` attribute within the jobs block, which told the workflow that the job is going to run using the GitHub-hosted runner that's running in the `ubuntu-latest` environment.

learn-pr/github/introduction-to-github/includes/2-what-is-github.md

@@ -120,11 +120,47 @@ Congratulations, you just created a new file in your repository! You have also c
 
 Before we review branches and commits in the next unit, let’s quickly review gists, wikis, and GitHub pages because they're similar to repositories.
 
-### What are gists
+### What are gists?
 
-Now that we have a good understanding of repositories, we can review gists. Similarly to repositories, gists are a simplified way to share code snippets with others.
+Gists are a feature of GitHub that allows users to share code snippets, notes, or other small pieces of information in a lightweight and convenient way. They are essentially mini Git repositories, which means you can fork, clone, and version-control them just like a full repository. Gists are particularly useful for sharing quick solutions, configuration files, or examples without the need to create a full repository.
 
-Every gist is a Git repository, which you can fork and clone and be made either public or secret. Public gists are displayed publicly where people can browse new ones as they’re created. Public gists are also searchable. Conversely, secret gists aren't searchable, but they aren’t entirely private. If you send the URL of a secret gist to a friend, they'll be able to see it.
+#### Key Features of Gists:
+1. **Public and Secret Gists**:
+   - **Public Gists**: These are visible to everyone and can be discovered through GitHub's search functionality. They are ideal for sharing code snippets or solutions that you want to make available to the broader community.
+   - **Secret Gists**: These are not searchable or publicly listed, but they are not entirely private. Anyone with the URL can access them. They are useful for sharing code with a limited audience, such as collaborators or friends.
+
+2. **Version Control**:
+   - Every change made to a gist is tracked, allowing you to view the history of edits. This makes it easy to revert to a previous version or see how the snippet has evolved over time.
+
+3. **Forking and Cloning**:
+   - Like repositories, gists can be forked and cloned. This allows others to build upon your work or adapt it to their needs.
+
+4. **Embedding**:
+   - Gists can be embedded into websites or blogs, making them a great tool for sharing code examples in tutorials or documentation.
+
+5. **Markdown Support**:
+   - Gists support Markdown formatting, which means you can include rich text, headings, links, and even images alongside your code. This is particularly useful for adding context or explanations to your snippets.
+   - Code blocks are automatically rendered with syntax highlighting, making your snippets easy to read.
+
+6. **Collaboration**:
+   - While gists are typically used for individual snippets, they can also be shared and collaborated on by multiple users. Forking and commenting on gists enable lightweight collaboration.
+
+#### Use Cases for Gists:
+- Sharing quick code examples or solutions.
+- Storing configuration files or scripts for personal use.
+- Creating templates for commonly used code patterns.
+- Sharing error logs or debugging information with others.
+- Embedding code snippets in blogs, forums, or documentation.
+
+[!IMPORTANT]
+> **Never use gists to store sensitive or confidential data, such as passwords, secrets, or API keys—even in scripts or config files.**  
+> Gists are not fully private: even secret gists can be accessed by anyone with the link. Always review your content carefully before sharing.
+
+#### Limitations of Gists:
+- Gists are not entirely private, even if marked as secret. Anyone with the URL can access them, so they should not be used for sensitive or confidential information.
+- They are best suited for small snippets or single files. For larger projects or multi-file structures, a full repository is more appropriate.
+
+To learn more about how to create and manage gists, refer to the GitHub documentation in the Resources section of this module or visit the [GitHub Gists documentation](https://docs.github.com/en/github/writing-on-github/creating-gists).
 
 ### Forking and cloning gists
 

learn-pr/github/manage-innersource-program-github/includes/2-manage-innersource-program.md

@@ -67,12 +67,18 @@ A README file communicates expectations for your project and helps you manage co
 - Include references to the projects on which you depend. These references are a good way to promote the work of others.
 - Use Markdown to guide readers through properly formatted content.
 
-If you put your README file in your repository's root directory, or in the hidden `.github` or `docs` directory, GitHub recognizes and automatically surfaces your README to repository visitors. If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the `.github` directory, then the repository's root directory, and finally the `docs` directory.
+If you put your README.md file in your repository's root directory, or in the hidden `.github` or `docs` directory, GitHub recognizes and automatically surfaces your README to repository visitors. If a repository contains more than one README file, then the file shown is chosen from locations in the following order: 
+1. The `.github` directory  
+2. The repository's root directory  
+3. The `docs` directory  
 
 Check out some [Awesome README examples](https://github.com/matiassingers/awesome-readme?azure-portal=true).
 
 Once the project launches, use email and other networking channels to promote it. Reaching an appropriate audience could produce a significant boost in project participation.
 
+[Learn more about README files in the GitHub documentation.](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
+
+
 ### Manage projects on GitHub
 
 As projects gain traction, the influx of users and contributions can require lots of work to manage. Depending on the project, a significant amount of work might be required just to manage the expectations of project participants.

learn-pr/github/manage-work-github-projects/7-knowledge-check.yml

@@ -69,3 +69,25 @@ quiz:
     - content: "Danger zone"
       isCorrect: true
       explanation: "Correct!"
+  - content: "What is the benefit of converting checklist items into sub-issues?"
+    choices:
+    - content: "It allows you to embed a checklist within an issue."
+      isCorrect: false
+      explanation: "Checklists are already supported in issues. Converting items creates trackable sub-issues."
+    - content: "It turns checklist items into standalone issues with status and metadata."
+      isCorrect: true
+      explanation: "Sub-issues appear as separate items with their own tracking in Projects."
+    - content: "It automatically resolves the parent issue."
+      isCorrect: false
+      explanation: "Sub-issues are linked but don't auto-close the parent issue."
+  - content: "Where can you go to enable default workflows for a Project?"
+    choices:
+    - content: "In the Project's README editor"
+      isCorrect: false
+      explanation: "README is for documentation, not automation."
+    - content: "From the three-dot menu in the top-right of your Project"
+      isCorrect: true
+      explanation: "The three-dot menu contains the Workflows option where default automation can be configured."
+    - content: "Under repository settings"
+      isCorrect: false
+      explanation: "Project workflows are configured within the Project view itself, not the repo settings."

learn-pr/github/manage-work-github-projects/includes/1-introduction.md

@@ -11,6 +11,8 @@ Learning objectives:
 - Understand how to organize your Project
 - Gain insight on how to edit the visibility, access, and management of your Project
 - Know how to develop automation and insights from your Project
+- Understand project layout options such as boards, lists, and timeline views
+- Learn how to convert checklist items into sub-issues
 
 Prerequisites:
 

learn-pr/github/manage-work-github-projects/includes/3-how-to-create-project.md

@@ -1,12 +1,14 @@
-Imagine you want to organize your team's feature backlog. Projects, GitHub's built-in program-management tool, is a perfect way to organize and prioritize your team's work in a single space.
+GitHub Projects is a powerful planning and tracking tool that gives your team flexible views—like tables, boards, and timelines—to organize your work and see the bigger picture.
+
+Imagine you want to manage your team’s feature backlog in one place. This built-in tool makes it easy to organize, prioritize, and track everything in a single view.
 
 In this unit, you learn how to:
 
 - Create a Project.
 - Set the name, description, and README of your Project.
 - Add issues and pull requests to your Project.
 
-## Creating an organization-level Project
+## Creating an organization-owned Project
 
 First, you want to lay the foundation by creating a new Project. Creating is relatively quick and simple.
 
@@ -24,7 +26,10 @@ First, you want to lay the foundation by creating a new Project. Creating is rel
 
 You just created a Project!
 
-You can also create a personal Project by selecting your profile photo and navigating to **Your projects**. Once you're on your Projects page, select the green button titled **New project**.
+> [!TIP]
+> You can also create a personal Project by selecting your profile photo and navigating to **Your projects**, then clicking **New project**.  
+> Additionally, Projects can be created directly from a repository—this links the repository to the Project automatically, though the Project itself is still created at the organization level and can be linked to other repositories or projects in the future.
+
 
 ## Set your Project's name, description, and README
 
@@ -78,4 +83,29 @@ You can bulk add issues and pull requests to an existing repository to save time
 
 1. Once you're ready to add the issues and pull requests to your Project, select the green button titled **Add selected items** in the bottom right corner.
 
+## Project workflows
+
+To help streamline work, GitHub Projects supports **default workflows**. These allow items like issues and pull requests to be automatically added to a Project and marked with an initial status, like "Todo".
+
+To enable a workflow:
+
+1. Open your Project.
+2. Select the three-dot menu in the top-right and choose **Workflows**.
+3. Choose a trigger like “Item added to project”.
+4. Set values, such as **Status: Todo**.
+5. Select **Save and turn on workflow**.
+
+## Convert checklist items into sub-issues
+
+As of February 2025, GitHub Projects supports converting checklist items into sub-issues. This feature makes it easier to break down tasks into smaller, trackable work items—directly from an issue.
+
+To convert a checklist item:
+
+1. Create or open an issue that contains a checklist.
+2. Hover over the checklist item.
+3. Click the **...** menu next to the item.
+4. Select **Convert to sub-issue**.
+
+This creates a linked issue that appears in your Projects view with its own status, metadata, and tracking. Sub-issues provide better visibility into related work and replace the older tasklist block feature, which was deprecated on April 30, 2025.
+
 In the next unit, you'll learn how to organize and prioritize your Project in order to keep your tasks on track.

learn-pr/github/manage-work-github-projects/includes/4-how-to-organize-your-project.md

@@ -83,3 +83,15 @@ Let's walk through how to get your board view up and running.
 Now, you can drag and drop issues and pull requests to the various columns.
 
    :::image type="content" source="../media/4-project-boards.png" alt-text="Screenshot example of a Project board with four columns labeled; no status, todo, in-progress, done.":::
+
+## Project workflows
+
+To automate common actions, GitHub Projects includes built-in workflows that help organize and update project items automatically. 
+
+For example, when a new issue is added to your Project, a default workflow can set its status to "Todo". Here's how to enable a workflow:
+
+1. Open your Project.
+2. Select the **⋯** menu in the top-right and choose **Workflows**.
+3. Select a trigger (e.g., "Item added to project").
+4. Configure values like **Status: Todo**.
+5. Click **Save and turn on workflow**.

learn-pr/github/manage-work-github-projects/includes/5-how-to-organize-automate-project.md

@@ -27,18 +27,18 @@ To change your Project's visibility:
 
 ### Manage access to your Project
 
-Access to your Project depends on if your Project is an organization-level Project or a personal/user-level Project. Managing access is similar between the two levels.
+Access to your Project depends on if your Project is an organization-owned Project or a personal/user-owned Project. Managing access is similar between the two levels.
 
-Admins of organization-level Projects can manage access for the entire organization, for teams, for individual organization members, and for outside collaborators. Admins of user-level Projects can invite individual collaborators and manage their access.
+Admins of organization-owned Projects can manage access for the entire organization, for teams, for individual organization members, and for outside collaborators. Admins of user-owned Projects can invite individual collaborators and manage their access.
 
-#### Organization-level Project
+#### Organization-owned Project
 
 - **No access**: Only organization owners and users granted individual access can see the Project. Organization owners are also admins for the Project.
 - **Read**: Everyone in the organization can see the Project. Organization owners are also admins for the Project.
 - **Write**: Everyone in the organization can see and edit the Project. Organization owners are also admins for the Project.
 - **Admin**: Everyone in the organization is an admin for the Project.
 
-#### Personal/User-level Project
+#### Personal/User-owned Project
 
 - **Read**: The individual can view the Project.
 - **Write**: The individual can view and edit the Project.
@@ -102,4 +102,16 @@ Here are steps on how to navigate to them:
 
    :::image type="content" source="../media/5-danger-zone-options.png" alt-text="Screenshot of the Danger zone section with the option to change visibility, close Project and delete Project with delete Project highlighted.":::
 
+## Converting checklist items to sub-issues
+
+GitHub Projects now supports converting checklist items into sub-issues for better task tracking and hierarchy.
+
+To use this feature:
+
+1. Open any issue that includes a checklist.
+2. Hover over a checklist item and click the **...** (more options) button.
+3. Select **Convert to sub-issue**.
+
+This creates a dedicated issue linked back to the original one, which will also appear in your Projects view for tracking.
+
 Next up, we'll review insights and automation in Projects.

learn-pr/github/manage-work-github-projects/includes/6-insight-automation-with-projects.md

@@ -87,4 +87,6 @@ Learn more about automating workflows for your Project in the article *Automatin
 
 ### GraphQL API
 
-If you're using GraphQL in GitHub, you can utilize an API to help automate your Project. For more information on using GraphQL API, see the article, *Using the API to Manage Projects* at the end of this module.
+If you're using GraphQL in GitHub, you can utilize this API to develop automation for your Project. For more information on using GraphQL API, see the article, *Using the API to Manage Projects* at the end of this module.
+
+