https://dailystuff.nlDailystuff on the Internet - Posts tagged GitHub Projects2024-03-16T09:59:03.445568+00:00ABloghttps://dailystuff.nl/blog/2023/add-issues-to-projects.htmlAdd issues to projects on GitHub2023-03-22T00:00:00+00:00Hans Spaans<section id="add-issues-to-projects-on-github">
<p>Adding issues to projects on GitHub is a great way to keep track of what needs to be done. This action will add issues to a project board on GitHub when they are opened or labeled. But adding issues to a project board is a manual process. The action <b class="github-object"><a class="reference external" href="https://github.com/actions/add-to-project">actions/add-to-project</a></b> automates the process of adding issues to a project board.</p>
<section id="setting-up-github">
<h2>Setting up GitHub</h2>
<p>In the workflows the environment variable <code class="docutils literal notranslate"><span class="pre">ADD_TO_PROJECT_URL</span></code> is used to define the project board. The project board is defined by the URL of the project board. The URL can be found in the browser when the project board is opened. The URL is defined in the <code class="docutils literal notranslate"><span class="pre">env</span></code> section of the workflow file.</p>
<p>The workflow also requires a personal access token (PAT) to authenticate with GitHub. The PAT is defined in the <code class="docutils literal notranslate"><span class="pre">secrets</span></code> section for Actions of the repository. The PAT is defined in the <code class="docutils literal notranslate"><span class="pre">github-token</span></code> input of the action.</p>
<img alt="Setting the PAT for GitHub Actions" src="https://dailystuff.nl/_images/add-issues-to-projects-2.webp" />
<p>If the repository also depends on DependaBot, then the workflow also requires a PAT to authenticate with GitHub. The PAT is defined in the <code class="docutils literal notranslate"><span class="pre">secrets</span></code> section for DependaBot of the repository. The PAT is defined in the <code class="docutils literal notranslate"><span class="pre">github-token</span></code> input of the action.</p>
<img alt="Setting the PAT for DependaBot" src="https://dailystuff.nl/_images/add-issues-to-projects-2.webp" />
</section>
<section id="adding-issues">
<h2>Adding issues</h2>
<p>The following workflow is triggered when an issues is opened and will add issues to a project board when they’re opened and it will use the labels on the issue to determine if it should be added to the project board. The labels are defined in the <code class="docutils literal notranslate"><span class="pre">labeled</span></code> input and the operator is defined in the <code class="docutils literal notranslate"><span class="pre">label-operator</span></code> input. The operator can be one of the following: <code class="docutils literal notranslate"><span class="pre">OR</span></code>, <code class="docutils literal notranslate"><span class="pre">AND</span></code>, or <code class="docutils literal notranslate"><span class="pre">NOT</span></code>.</p>
<div class="literal-block-wrapper docutils container" id="id1">
<div class="code-block-caption"><span class="caption-text">Workflow file <code class="file docutils literal notranslate"><span class="pre">.github/workflows/add-to-project.yml</span></code> for GitHub Actions</span></div>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="nn">---</span>
<span class="linenos"> 2</span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add to project board</span>
<span class="linenos"> 3</span>
<span class="linenos"> 4</span><span class="nt">on</span><span class="p">:</span>
<span class="linenos"> 5</span><span class="w"> </span><span class="nt">issues</span><span class="p">:</span>
<span class="linenos"> 6</span><span class="w"> </span><span class="nt">types</span><span class="p">:</span>
<span class="linenos"> 7</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">opened</span>
<span class="linenos"> 8</span>
<span class="linenos"> 9</span><span class="nt">env</span><span class="p">:</span>
<span class="linenos">10</span><span class="w"> </span><span class="nt">ADD_TO_PROJECT_URL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://github.com/users/acme/projects/1</span>
<span class="linenos">11</span>
<span class="linenos">12</span><span class="nt">jobs</span><span class="p">:</span>
<span class="linenos">13</span><span class="w"> </span><span class="nt">add-to-project</span><span class="p">:</span>
<span class="linenos">14</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add issue to project</span>
<span class="linenos">15</span><span class="w"> </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ubuntu-latest</span>
<span class="linenos">16</span><span class="w"> </span><span class="nt">steps</span><span class="p">:</span>
<span class="linenos">17</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/add-to-project@v0.4.0</span>
<span class="linenos">18</span><span class="w"> </span><span class="nt">with</span><span class="p">:</span>
<span class="linenos">19</span><span class="w"> </span><span class="nt">project-url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ env.ADD_TO_PROJECT_URL }}</span>
<span class="linenos">20</span><span class="w"> </span><span class="nt">github-token</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ secrets.ADD_TO_PROJECT_PAT }}</span>
<span class="linenos">21</span><span class="w"> </span><span class="nt">labeled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bugs, enhancement, policy, project, security, stale</span>
<span class="linenos">22</span><span class="w"> </span><span class="nt">label-operator</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">OR</span>
</pre></div>
</div>
</div>
</section>
<section id="adding-pull-requests">
<h2>Adding pull-requests</h2>
<p>The workflow can also be triggered when a pull-request is labeled. This is different from the previous workflow as that workflow only was triggered when an issue was opened. The rest of the workflow is the same as the previous workflow, but the <code class="docutils literal notranslate"><span class="pre">labeled</span></code> section is different.</p>
<div class="literal-block-wrapper docutils container" id="id2">
<div class="code-block-caption"><span class="caption-text">Workflow file <code class="file docutils literal notranslate"><span class="pre">.github/workflows/add-to-project.yml</span></code> for GitHub Actions</span></div>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="nn">---</span>
<span class="linenos"> 2</span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add to project board</span>
<span class="linenos"> 3</span>
<span class="linenos"> 4</span><span class="nt">on</span><span class="p">:</span>
<span class="linenos"> 5</span><span class="w"> </span><span class="nt">pull_request</span><span class="p">:</span>
<span class="linenos"> 6</span><span class="w"> </span><span class="nt">types</span><span class="p">:</span>
<span class="linenos"> 7</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">labeled</span>
<span class="linenos"> 8</span>
<span class="linenos"> 9</span><span class="nt">env</span><span class="p">:</span>
<span class="linenos">10</span><span class="w"> </span><span class="nt">ADD_TO_PROJECT_URL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://github.com/users/acme/projects/1</span>
<span class="linenos">11</span>
<span class="linenos">12</span><span class="nt">jobs</span><span class="p">:</span>
<span class="linenos">13</span><span class="w"> </span><span class="nt">add-to-project</span><span class="p">:</span>
<span class="linenos">14</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add issue to project</span>
<span class="linenos">15</span><span class="w"> </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ubuntu-latest</span>
<span class="linenos">16</span><span class="w"> </span><span class="nt">steps</span><span class="p">:</span>
<span class="linenos">17</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/add-to-project@v0.4.0</span>
<span class="linenos">18</span><span class="w"> </span><span class="nt">with</span><span class="p">:</span>
<span class="linenos">19</span><span class="w"> </span><span class="nt">project-url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ env.ADD_TO_PROJECT_URL }}</span>
<span class="linenos">20</span><span class="w"> </span><span class="nt">github-token</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ secrets.ADD_TO_PROJECT_PAT }}</span>
<span class="linenos">21</span><span class="w"> </span><span class="nt">labeled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dependencies, stale</span>
<span class="linenos">22</span><span class="w"> </span><span class="nt">label-operator</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">OR</span>
</pre></div>
</div>
</div>
<p>Until now the label-operator was <code class="docutils literal notranslate"><span class="pre">OR</span></code>, but now it’s <code class="docutils literal notranslate"><span class="pre">AND</span></code> in the next examepl. This means that the issue will only be added to the project board if it has both the <code class="docutils literal notranslate"><span class="pre">github</span></code> and <code class="docutils literal notranslate"><span class="pre">policy</span></code> labels.</p>
<div class="literal-block-wrapper docutils container" id="id3">
<div class="code-block-caption"><span class="caption-text">Workflow file <code class="file docutils literal notranslate"><span class="pre">.github/workflows/add-to-project.yml</span></code> for GitHub Actions</span></div>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="nn">---</span>
<span class="linenos"> 2</span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add to project board</span>
<span class="linenos"> 3</span>
<span class="linenos"> 4</span><span class="nt">on</span><span class="p">:</span>
<span class="linenos"> 5</span><span class="w"> </span><span class="nt">pull_request</span><span class="p">:</span>
<span class="linenos"> 6</span><span class="w"> </span><span class="nt">types</span><span class="p">:</span>
<span class="linenos"> 7</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">labeled</span>
<span class="linenos"> 8</span>
<span class="linenos"> 9</span><span class="nt">env</span><span class="p">:</span>
<span class="linenos">10</span><span class="w"> </span><span class="nt">ADD_TO_PROJECT_URL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://github.com/users/acme/projects/1</span>
<span class="linenos">11</span>
<span class="linenos">12</span><span class="nt">jobs</span><span class="p">:</span>
<span class="linenos">13</span><span class="w"> </span><span class="nt">add-to-project</span><span class="p">:</span>
<span class="linenos">14</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add issue to project</span>
<span class="linenos">15</span><span class="w"> </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ubuntu-latest</span>
<span class="linenos">16</span><span class="w"> </span><span class="nt">steps</span><span class="p">:</span>
<span class="linenos">17</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/add-to-project@v0.4.0</span>
<span class="linenos">18</span><span class="w"> </span><span class="nt">with</span><span class="p">:</span>
<span class="linenos">19</span><span class="w"> </span><span class="nt">project-url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ env.ADD_TO_PROJECT_URL }}</span>
<span class="linenos">20</span><span class="w"> </span><span class="nt">github-token</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ secrets.ADD_TO_PROJECT_PAT }}</span>
<span class="linenos">21</span><span class="w"> </span><span class="nt">labeled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github, policy</span>
<span class="linenos">22</span><span class="w"> </span><span class="nt">label-operator</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">AND</span>
</pre></div>
</div>
</div>
</section>
<section id="combining-issues-and-pull-requests">
<h2>Combining issues and pull-requests</h2>
<p>In the previous example the workflow was triggered when an issue was opened and when a pull-request was labeled. But the workflow can also be triggered when an issue is labeled and when a pull-request is opened. Secondly it can have multiple steps to select the labels and the operator to add issues and pull-request to the project board.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Currently this action supports the following <code class="docutils literal notranslate"><span class="pre">issues</span></code> events:</p>
<ul class="simple">
<li><p>opened</p></li>
<li><p>transferred</p></li>
<li><p>labeled</p></li>
</ul>
<p>and the following <code class="docutils literal notranslate"><span class="pre">pull_request</span></code> events:</p>
<ul class="simple">
<li><p>opened</p></li>
<li><p>labeled</p></li>
</ul>
</div>
<p>Combining issues and pull-requests to a single workflow with multiple steps to add issues and pull-requests to a project board is shown in the following example. It will add issues to a project board when they are opened and labeled. It will also add pull-requests to a project board when they are labeled. This allows for more flexibility in the workflow and selecting the labels and the operator to add issues and pull-requests to the project board.</p>
<div class="literal-block-wrapper docutils container" id="id4">
<div class="code-block-caption"><span class="caption-text">Workflow file <code class="file docutils literal notranslate"><span class="pre">.github/workflows/add-to-project.yml</span></code> for GitHub Actions</span></div>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="nn">---</span>
<span class="linenos"> 2</span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add to project board</span>
<span class="linenos"> 3</span>
<span class="linenos"> 4</span><span class="nt">on</span><span class="p">:</span>
<span class="linenos"> 5</span><span class="w"> </span><span class="nt">issues</span><span class="p">:</span>
<span class="linenos"> 6</span><span class="w"> </span><span class="nt">types</span><span class="p">:</span>
<span class="linenos"> 7</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">opened</span>
<span class="linenos"> 8</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">labeled</span>
<span class="linenos"> 9</span><span class="w"> </span><span class="nt">pull_request</span><span class="p">:</span>
<span class="linenos">10</span><span class="w"> </span><span class="nt">types</span><span class="p">:</span>
<span class="linenos">11</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">labeled</span>
<span class="linenos">12</span>
<span class="linenos">13</span><span class="nt">env</span><span class="p">:</span>
<span class="linenos">14</span><span class="w"> </span><span class="nt">ADD_TO_PROJECT_URL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://github.com/users/acme/projects/1</span>
<span class="linenos">15</span>
<span class="linenos">16</span><span class="nt">jobs</span><span class="p">:</span>
<span class="linenos">17</span><span class="w"> </span><span class="nt">add-to-project</span><span class="p">:</span>
<span class="linenos">18</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Add issue to project</span>
<span class="linenos">19</span><span class="w"> </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ubuntu-latest</span>
<span class="linenos">20</span><span class="w"> </span><span class="nt">steps</span><span class="p">:</span>
<span class="linenos">21</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/add-to-project@v0.4.0</span>
<span class="linenos">22</span><span class="w"> </span><span class="nt">with</span><span class="p">:</span>
<span class="linenos">23</span><span class="w"> </span><span class="nt">project-url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ env.ADD_TO_PROJECT_URL }}</span>
<span class="linenos">24</span><span class="w"> </span><span class="nt">github-token</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ secrets.ADD_TO_PROJECT_PAT }}</span>
<span class="linenos">25</span><span class="w"> </span><span class="nt">labeled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bugs, enhancement, policy, project, security, stale</span>
<span class="linenos">26</span><span class="w"> </span><span class="nt">label-operator</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">OR</span>
<span class="linenos">27</span>
<span class="linenos">28</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/add-to-project@v0.4.0</span>
<span class="linenos">29</span><span class="w"> </span><span class="nt">with</span><span class="p">:</span>
<span class="linenos">30</span><span class="w"> </span><span class="nt">project-url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ env.ADD_TO_PROJECT_URL }}</span>
<span class="linenos">31</span><span class="w"> </span><span class="nt">github-token</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ secrets.ADD_TO_PROJECT_PAT }}</span>
<span class="linenos">32</span><span class="w"> </span><span class="nt">labeled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dependencies, stale</span>
<span class="linenos">33</span><span class="w"> </span><span class="nt">label-operator</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">OR</span>
<span class="linenos">34</span>
<span class="linenos">35</span><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">actions/add-to-project@v0.4.0</span>
<span class="linenos">36</span><span class="w"> </span><span class="nt">with</span><span class="p">:</span>
<span class="linenos">37</span><span class="w"> </span><span class="nt">project-url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ env.ADD_TO_PROJECT_URL }}</span>
<span class="linenos">38</span><span class="w"> </span><span class="nt">github-token</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">${{ secrets.ADD_TO_PROJECT_PAT }}</span>
<span class="linenos">39</span><span class="w"> </span><span class="nt">labeled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github, policy</span>
<span class="linenos">40</span><span class="w"> </span><span class="nt">label-operator</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">AND</span>
</pre></div>
</div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This workflow is based on the <b class="github-object"><a class="reference external" href="https://github.com/actions/add-to-project">actions/add-to-project</a></b> action, but GitHub has since added the ability to add issues to a project board <a class="reference external" href="https://github.blog/changelog/2023-03-09-github-issues-projects-march-9th-update/">automatically</a> and is in beta for now together with automatically archiving project items.</p>
</div>
</section>
</section>
Adding issues to projects on GitHub is a great way to keep track of what needs to be done. This action will add issues to a project board on GitHub when they are opened or labeled. But adding issues to a project board is a manual process. The action actions/add-to-project automates the process of adding issues to a project board.In the workflows the environment variable ADD_TO_PROJECT_URL is used to define the project board. The project board is defined by the URL of the project board. The URL can be found in the browser when the project board is opened. The URL is defined in the env section of the workflow file.Setting the PAT for GitHub Actions2023-03-22T00:00:00+00:00