diff --git a/docs/tutorials/getting-started.rst b/docs/tutorials/getting-started.rst index 8516b4766..12178f3ae 100644 --- a/docs/tutorials/getting-started.rst +++ b/docs/tutorials/getting-started.rst @@ -13,91 +13,86 @@ with your repo in as few steps as possible. There are three steps to getting running tasks: -1. Install Taskcluster Github +1. Define Tasks 2. Request Permissions -3. Define Tasks +3. Install Taskcluster Github Let's dive into each! -Install Taskcluster Github --------------------------- +Create Tasks +------------ -.. note:: +The first step is to define your tasks. You'll need: - If you are not using Github, skip to the next section. +1. A :term:`Decision Task` defined in ``.taskcluster.yml`` +2. A Taskgraph setup in the ``taskcluster`` directory -Each Taskcluster deployment has an associated Github app that needs to be added -to your repo. Some apps for known Taskcluster deployments are as follows: +Luckily Taskgraph provides an ``init`` command that can generate both of these +things automatically! Run: -.. list-table:: Taskcluster Github Apps - :widths: 20 60 - :header-rows: 1 +.. code-block:: shell + + $ pip install taskcluster-taskgraph + $ taskgraph init - * - Instance - - Github App - * - `Firefox-CI `_ - - https://github.com/apps/firefoxci-taskcluster - * - `Community `_ - - https://github.com/apps/community-tc-integration +This will automatically generate all the necessary files. Commit what was +generated: -Follow the link to the Github app for your deployment and click ``Configure`` -near the top right. Then select the repository you'd like to enable. If you are -not an admin of the organization you are enabling the repo for, this will send -a request to your Github administrators. +.. code-block:: shell -.. note:: + $ git add . + $ git commit -m "Add Taskcluster files" - If you do not see a ``Configure`` button, contact your Github administrators - for assistance. +Land your changes on the default branch (typically ``main``). Nothing will +happen yet, but we need that ``.taskcluster.yml`` file to exist at the root of +the repository for the next step. Request Permissions ------------------- -Your repository is now connected to Taskcluster, but it won't have permission -to run anything. In the Taskcluster world, permissions are also known as -:term:`scopes `. So the next step is to contact your Taskcluster -administrators and request scopes for your project so that it has access to the -resources it needs to run tasks. +Your repository now has some tasks defined, but it won't have permission to run +anything. In the Taskcluster world, permissions are also known as :term:`scopes +`. So the next step is to contact your Taskcluster administrators and +request scopes for your project so that it has access to the resources it needs +to run tasks. -Each Taskcluster instance can be managed differently, but here are the processes -to request scopes for some known Taskcluster deployments: +.. note:: -.. list-table:: Taskcluster Github Apps - :widths: 20 60 - :header-rows: 1 + For Mozilla's `Firefox-CI `_ instance, + file a bug under `Release Engineering :: Firefox-CI Administration + `_ - * - Instance - - Process - * - `Firefox-CI `_ - - `File a Bug `_ - * - `Community `_ - - `File an Issue `_ + Use a title such as: *Please setup `org/my-repo` with Taskcluster*. -Use a title such as: *Please setup `org/my-repo` with Taskcluster*. +Install Taskcluster Github +-------------------------- -Create Tasks ------------- +.. note:: -The last step is to define your tasks. You'll need: + If you are not using Github, skip this section and reach out to your + Taskcluster administrators, there may be other steps to integrate your + repository. -1. A :term:`Decision Task` defined in ``.taskcluster.yml`` -2. A Taskgraph setup in the ``taskcluster`` directory +Each Taskcluster deployment has an associated Github app that needs to be added +to your repo. If you are unsure which app your deployment uses, ask your +Taskcluster administrators. -Luckily Taskgraph provides an ``init`` command that can generate both of these -things automatically! Run: +.. note:: -.. code-block:: shell + The Github app for Mozilla's `Firefox-CI + `_ instance can be found here: - $ pip install taskcluster-taskgraph - $ taskgraph init + https://github.com/apps/firefoxci-taskcluster -This will automatically generate all the necessary files. Commit what was -generated: +Open the page of the Github app for your deployment and click ``Configure`` +near the top right. Then select the repository you'd like to enable. If you are +not an admin of the organization you are enabling the repo for, this will send +a request to your Github administrators. -.. code-block:: shell +.. note:: - $ git add . - $ git commit -m "Add Taskcluster files" + If you do not see a ``Configure`` button, contact your Github administrators + for assistance. Now when you push, you should have a working Decision task that generates a ``hello-world`` task as well as a ``docker-image`` task that it depends on!